A.C.E. 2/ACE CD 2.iso/FILES/DOCS/AMOSDOC.LHA/AmosPart4.doc

Text File | 1994-11-27 | 148.8 KB | 4,352 lines

15: BACKGROUND GRAPHICS

Nowadays, it's not uncommon for an arcade game to contain hunderds of
different screens. With compaction, it's possible to crap a single 32
colour screen into about 30k of memory. So 100 screens would be the
equivalent of about 3 Megabytes of data. Imagine how difficult this
would be to fit into a standard A500!

  The classic way of avoiding this restriction, is to construct your
backgrounds out of a set of simple building blocks. Once these "tiles"
have been created, they can be placed on the screen in any order you
like. So the same set of tiles can be reused to generate a vast number
of potential screens. Each screen is now stored as a simple list of its
components, and requires a tiny fraction of the original memory.

  In order to exploit this system, you'll obviously need some way of
defining your various screen maps. As you might have guessed, we've
helpfully provided you with a powerful map definer accessory on the
AMOS program disc. Full details can be found in the accompanying
documentation file.

  AMOS Basic also includes a number of special instructions for drawing
your tiles on the screen. These make it easy to generate the fast
scrolling backgrounds that are the hallmark of a modern arcade game.


Icons
=====
Icons are separate images which have been especially designed for
producing your background screens. Once you've drawn an icon, it's
fixed permanently into place. So you can't move it to a new position
using the AMAL animation system.

  All icons are stored in their own AMOS memory bank (#2). This bank is
created using the Sprite definer accessory (on the AMOS Program disk),
and will be automatically saved along with your Basic programs.

  Like Bobs, Icons are displayed using the Amiga's amazing Blitter
chip. But since Icons are essentally static objects, they are usually
drawn in REPLACE mode. Your icons will therefore totally erase any
existing graphics at the current screen position.



                       PASTE ICON (draw an icon)

PASTE ICON x,y,n

Draws icon number n on the screen at GRAPHIC coordinates x,y. n is the
number of the icon which is to be displayed. This must have been
previously stored in the ICON bank.

  Icons can be freely positioned anywhere on the screen, subject to the
normal clipping rules. Example:

        Load "AMOS_DATA:Icons/Map_icons.abk"
        Screem Open 0,320,256,32,Lowres : Cls 0 : Get Icon Palette
        For X=1 To 11 : Paste Icon X*32,0,1 : Next X
        For Y=1 To 6 : Paste Icon 0,Y*32+11 : Paste Icon 288,Y*32,1
        Next Y
        For X=1 To 11 : Paste Icon X*32,223,1 : Next X

Note that if you're using double buffering, a copy of your icons will
be drawn into both the physical and logical screens. Since this is
rather slow, it's common practive to add a call to AUTOBACK 0 before
drawing your icons on the screen. This restricts straight to the
physical screen using SCREEN COPY, saving a considerable amount of
time.

  For a further example, see the MAPVIEW program on the AMOS DATA disc.
This displays a background screen you've created using the AMOS Map
Editor.



                       GET ICON (create an icon)                           208

GET ICON [s,] i,tx,ty TO bx,by

Captures an image from the screen and loads it into icon "i". If this
icon does not presently exist, it will be created for you in bank 2.
This bank will be automatically reserved by the system if required.

  i is the number of your icon, starting from 1. tx,ty to bx,by define
the rectangular zone which encloses the selected region.

  s determines the number of the screen which will be used as the
source of your image. If it's omitted, the image will be taken from the
current screen instead. Example:

        Erase 2
        F$=Fsel$("*.*","","Load a screen") : If F$="" Then Direct
        If Exist(f$) Then Load Iff f$,0 Else Direct
        SH=Screen Height : H=SH/32-1 : SW=Screen Width : W=SW/32-1
        For Y=0 to H
          For X=0 to W
            Get Icon X+Y*W+1,X*32,Y*32 To X*32+31,Y*32+31
          Next X
        Next Y
        Cls 0
        Do
          Paste Icon Rnd(Sw-1),Rnd(SH-1),Rnd/(H*W)+1
        Loop



                  GET ICON PALETTE (get icon colours)

GET ICON PALETTE

Grabs the colours of the icon images in bank 2, and loads them into the
current screen palette. This command is normally used to initialize the
screen after you'be loaded some icons from the disc. Example:

        Load "AMOS_DATA:Icons/Map_icons.abk"
        Get Icon Palette
        Paste Icon 100,100,1



                       DEL ICON (deletes icons)                            209

DEL ICON n[ TO m]

Deletes one or more icons from the icon bank. n is the number of the
first icon to be removed.

  m is the optional number of the last icon to be deleted in the list.
If it's included all the icons from first to last will be erased one
after another.

  When the final icon in a bank has been deleted, the entire bank will
be removed from memory.



            MAKE ICON MASK (set colour zero to transparent)

MAKE ICON MASK [n]

Normally, any icons you draw on the screen will completely replace the
existing background. The icon will seem to be displayed in a
rectangular box filled with colour zero.

  If you want to avoid this effect and overlay your icons directly over
the current graphics, you'll need to create a *mask* for your icons.
This informs AMOS that colour zero should be treated as transparent.

  n is the number of the icon to be affected. If it's omitted, a mask
will be defined for all icons in the bank. See EXAMPLE 15.1


Screen blocks
=============
AMOS Basic supplies you with a set of powerful BLOCK commands which
allow you to grab part of an image into memory and paste it anywhere on
the screen.

        These instructions are mainly used for holding temporary data,
since your blocks cannot be saved along with your Basic programs.

  Blocks are especially effective in the construction of dialogue
boxes, as they can be used to save the background areas before
displaying your new graphics.

  They can also be exploited in puzzle games like Split Personalities.
Each block can be loaded with a single section of your image. You can
then jumble your pictures by rearranging the blocks on the screen with
PUT BLOCK.



              GET BLOCK (grab a screen block into memory)

GET BLOCK n,tx,ty,w,h[,mask]

GET BLOCK grabs a rectangular area in block number n, starting at
coordinates tx,ty.

  n is the number of the block ranging from 1-65535. tx, ty set the
coordinates of the top left hand corner of your block. w,y hold the
width and height of the block respectively.

  "mask" is a flag which chooses whether a mask will be created for
your new block.

  mask=0        Replace mode. When the block is drawn on the screen,
                it will totally destroy any graphics at that current
                position.
  mask=1        Calculates a mask for the block. Colour zero will now
                be treated as if it were transparent.



                PUT BLOCK (copies a previously created                     210
                        block onto the screen)

PUT BLOCK n[,x,y]
PUT BLOCK n,x,y,planes[,minterms]

PUT BLOCK copies block number n to the current screen. x,y specify the
position of your new block on the screen. If they are omitted the block
will be redrawn at its original screen coordinates.

  Note that all drawing operations will be clipped to fit into the
current screen, starting from the nearest 16 pixel boundary.

  For a demostration of the BLOCK commands see the routine in EXAMPLE
15.2. We've also provided experienced programmers with a couple of
optional extras. These are not needed for the vast majority of
applications, they're only required when you want to achieve weird
special effects on the screen!

  "planes" holds a bit-map which sets the range of colours which will
be drawn in your block. The Amiga's screen is divided up into segments
known as bit-planes. Each plane contains a single bit for every point
on the Amiga's screen. When the Amiga's hardware displays this point,
it combines the bits from each plane to calculate the required colour
number. Each bit in "planes" represents the status of a single
bit-plane. If it's set to one, then the selected plane will be drawn by
the instruction, otherwise it will be completely ignored. The first
plane is represented by bit zero, the second by bit one, etc.

  Usually, the block will be displayed in all the available bit-planes.
The corresponds to a bit-pattern of %111111

  "minterm" selects the blitter mode used to copy your block on the
screen. A full description of the possible drawing modes can be found
in the section on SCREEN COPY. The best way to loearn about these
options is to experiment!



                   DEL BLOCK (delete a screen block)

DEL BLOCK n

Deletes one or more blocks and restores the memory used to AMOS Basic.

DEL BLOCK       Erases *all* current blocks
DEL BLOCK n     Deletes block number n.



             GET CBLOCK (save and compact a screen image)                  211

GET BLOCK n,x,y,sx,sy

The GET BLOCK command saves and compacts a rectangular area of the
screen. The compaction system used by this command has been especially
optimized for speed. So it's nowhere near as efficient as the dedicated
AMOS compression routines provided by the PACK or SPACK instructions.

  CBLOCKS are often used to grab the area underneath your dialogue
boxes. After the dialogue has been completed, the screen can quickly
restored back to its original state. See EXAMPLE 15.3.

  n specifies the number of your block and can range between 1-65535.

  x,y are the top left coordinates. The x coordinate is rouded to the
nearest multiple of 8.

  w,h hold the dimensios of the area to be saved. The width is always
rounded to an exact multiple of 8.



                     PUT CBLOCK (displays a block
                         created using CBLOCK)

PUT CBLOCK n [,x,y]

Places block n on the current screen at coordinates x,y. If the target
coordinates are omitted, the block will be redrawn at its original
screen position. Also note that x is automatically rounded to the
nearest eight pixel boundary.



                  DEL CBLOCK (deletes a screen block
                       defined with GET CBLOCK)

DEL CBLOCK [n]

Erases all blocks from memory. If n is present only block n will be
deleted.







                               16: MENUS                                   212
                      ---------------------------

If you've used the Amiga for some time you'll already be familiar with
the idea of menus. Impossible as it seems, AMOS has taken the existing
system and improved it almost beyond recognition.

  Menus can be created with up to eight separate levels, and each
individual menu item can be repositioned on the screen at will. Menu
titles can be printed in any combination of colours or styles. You can
also include bobs or icons directly in your menus using an amazing menu
definition language.

  AMOS Basic is equally impressive when it comes to reading a menu.
There's a buit-in interrupt-dricen ON MENU command which can
automatically branch to a selected point in your program depending on
the option selected. Furthermore, any menu option can be accessed
directly from the keyboard using the MENU KEY instruction.

  For a demonstration of the terrific effects that can be achieved with
this system, load the program EXAMPLE 16.1.


Using a menu
============
All AMOS menus are called up by holding down the right mouse button in
the standard way. Once a menu has been activated you can then select an
option directly with the mouse cursor. When you release the button, the
option number you have chosen will be returned to your program.

  Menus can be repositioned by placing the mouse cursor over the top
left corner of an item and holding down the LEFT button. A small box
will now appear on the menu bar which can be dragged across the screen
using the mouse.

  In addition, holding down the SHIFT key will freeze a menu into
place. This allows you explore a menu without selecting any of the
various options. You can also use any of the mouse features such as
slowing or axis selection in conjunction with your menus.


Creating a simple menu
======================
AMOS menus can be created either directly within your programs or using
a special menu definer included on the AMOS program disc.

  If you've never used menus before, the sheer variety of the available
menu commands may seem a little overwhelming. Here's a brief
description of the basic features to provide you with a painless
introduction to AMOS menus.


Setting the title line
----------------------
The first stage in the creation of a menu is to define the "title
line". THe title line of a menu can be set using the MENU$ command. In
its simplest form this has the format:



                       MENU$ (set a menu title)

MENU$(n)=title$

MENU$ creates a title line for your menu. Each heading is assigned it's
own individual number starting from one, and increasing from left to
right. So the leftmost title is repsresented by a one, the next title
as two, etc.

  The text in "title$" holds the name of the option which will be
displayed in your new menu. Here is a simple example which constructs a
menu line consisting of just two titles: ACTION and MOUSE

        Menu$(1)=" Action "
        Menu$(2)=" Mouse "

Note the space after "Action" - this will separate it from Mouse, the
next menu along. You must now specify a list of options to be              213
associated with each of your new headings. These form a vertical bar
which will drop into place whenever a title is selected with the mouse.



                    MENU$(t,o)  (set a menu option)

MENU$(t,o)=option$

This second form of MENU$ defines a set of options which will be
displayed in the menu bar.

  t is the number of menu heading which your option will displayed
under. o is the option number you with to install in the menu bar.
All options are numbered downwards from the top of the menu, starting
from one.

  The only physical limit to the size of your menu is the amount of
memory, but it's wise to restrict yourself to less than about 10
options for each title. This will keep the complexity of your menus
down to an agreeable minimum.

  "option$" holds the name of your new option. This can consist of any
section of text you like. For an example, try adding the following
lines to the program above:

        Rem Action menu
        Menu$(1,1)=" Quit "
        Rem Mouse menu
        Menu$(2,1)=" Arrow "
        Menu$(2,2)=" Pointer "
        Menu$(2,3)=" Clock "
        Wait Key

This specifies a list of alternatives for the ACTION and the mouse
menus. If you try to run this program as it stands, nothing will
happen. That's because the menus need to be initialised with a call to
the MENU ON command. Enter this thin above program before the Wait Key
instruction. Now run the example and select the menu items with the
mouse cursor. Remember to hold down the RIGHT mouse button first!



                        MENU ON (activate menu)

MENU ON

Activates a menu defined using the MENU$ command. The menu line will
now appear automatically when the right mouse button is pressed ny the
user. To start the previous menu, insert the following line after the
definition statements.

        Menu On

Go to the Direct window and play around with the menus. Select options     214
by pressing the right mouse button


Reading a simple menu
=====================
Once you've created your menu and activated the AMOS menuing system
you'll want to discover which options have been selected by the user.
This can be accomplished using a simple form of the CHOICE command.



                         =CHOICE (read a menu)

selected=CHOICE

CHOICE returns a value of -1 (true) if the menu has been highlighted by
the user, otherwise 0. It's automatically reset to 0 after each test.
It's also possible to find the title number which has been selected
using a second form of this instruction.

heagind=CHOICE(1)

"heading" now contains the number of the "title" which has been
highlighted by the user. Similarly you can retrieve the actual option
number which has been chosen with a parameter of two.

item=CHOICE(2)

Try adding the following lines to the previous example:

        Do
          Rem If choice=-1 can be simplified to: If choice, as seen...
          If choice and choice(1)=1 Then Exit
          If choice(1)=2 and choice(2)<>0 Then Change Mouse choice(2)
        Loop

This changes the shape of the mouse cursor depending on which option
you have chosen from the menu. A full demonstration of these menu can
be found in the file EXAMPLE 16.2.


Advanced menuing features
-------------------------
We will now cover some of the more advanced menuing features available
from within AMOS Basic. Used properly these AMOS menus can add a whole
new dimension to your programs.




                         MENU$ (create a menu)                             215

MENU$(,,)=normal$[,selected$][,inactive$][,background$]

Defines the appearance of each individual menu item in one of your
menus. Unlike normal Amiga menus these items are not restricted to
standard text. They can also include embedded commands which allow you
to draw bobs, icons or graphics at any point in the menu line.

  Any of the parameters in this instruction may be optionally omitted,
so you can change parts of a menu description indenpendently. A value
of "" in your menu string will ERASE the existing setting. Similarly
you can retain the original value by including a comma at the
appropriate point. For example:

        Menu$(1)=" Action ","" : Rem Erase second option
        Menu$(2)=" Mouse 2 ",, : Rem Change title without altering
                                     anything else.

The position of the menu item within the actual menu is indicated using
a list of up to eight parameters separated by commas. The general
format is:

        (item)/(item,option)/(item,option,sub option)...

"normal$" is a string which sets the normal appearance of an item when
it's displayed in the menu. "selected$" changes the effect of
highlighting a menu option with the mouse. As a default, selected items
are printed in inverse text.

  "inactive$" changes the appearance of an item which has been
deactivated using the MENU INACTIVE command. If this string is omitted,
all inactive imtes will be displayed in italics. "background$" creates
a background for your menu items when they are initially drawn.
Generally this will be a bo of some sort created with the internal Bar
or line commads.

  For now one, we'll abbreviate these parameters using a standard
notation:

        setting$=[,selected$][,inactive$][,background$]


The menu hierarchy
------------------
The level of an item in the menu is determined by its position in the
menu hierarchy.

        Menu$(1)="Title"
        Menu$(1,1)="Option 1"
        Menu$(1,2)="Option 2"
        Menu$(1,2,1)="Item 1"

This defines a simple menu. The structure of a menu is similar to that
of an array. Each level of the menu is represented by its own dimension
in the array, and is controlled using a separate version of the MENU$
command.

  The first level represents the title line which appears at the top of
your menus. It can be set using a command like:

        Menu$(n)=title$[setting$]

"n" now corresponds to the position of the title from the left of the      216
screen, and setting$ refers to the three optional strings which define
the general appearance of the menu. It's important to define the title
of your menus first as this *dimensions* the array. All other items may
be created in any order you wish.

  Each title is associated with a list of menu options which drop into
view when the menu is selected. These form the second level of the menu
structure and are defined using a second version of the MENU$ command.

        Menu$(n,option)=Item$[setting$]

"option" holds the number of the item measured from the top left of the
menu bar. There's no limit to the number of options which may be linked
to a single title, other than the amount of available memory.

  Each individual option can in turn be associated with its own sub
menus up to a total of eight levels.

        Menu$(n,option,sub option)=Item$[setting$]

Once you've created a menu it can be expanded or changed at any point
in your program. Never change the current screen while you are creating
a menu as this will lead to an error message.

See EXAMPLE 16.3



                          =CHOICE (read menu)

item=CHOICE[(dimension)]

The CHOICE function checks whether an option has been highlighted on
the current menu. If an item has been selected (down to the lowest
level), CHOICE will return a value of -1, otherwise it will be 0. After
you've called this function, the status of the menu will be
automatically restored to 0 (false). This stops a single menu access
from being accidentally detected several times.

  The second form of this command returns the option selected at the
required level.

item=CHOICE(dimension)

"dimension" indicates the level of the menu which is to be read. As you
may recall, a level number of 1 corresponds to the title line of the
menu. Similartly the levels between 2 and 8 indicate the number of an
ioption which has been chosen. If a menu item has not been selected,
"item" will be loaded with a value of zero. For example:

        Menu$(1)="Menu"
        Menu$(1,1)="Option 1"
        Menu$(1,2)="Option 2"
        Menu$(1,2,1)="Option 2.1"
        Menu On
        Do
          If choice Then Print choice(1),choice(2),choice(3)
        Loop

If you wanted to implement larger menus with this system, your program
would need to use a long list of IF...THEN statements to deal with each
and every possibility. This would cause a small but significant delay
in your program while the menus were being read. It would also make it
very difficult to amend your program later. Fortunately AMOS Basic
provides you with a painless method of managing even the largest menus.



                ON MENU PROC (automatic menu selection)                    217

ON MENU PROC proc1 [,proc2,...]

Each title in your menu can be assigned its own procedure which will be
executed automatically whenever an option is selected by the user. The
action of this command is similar to the code below:

        If Choice
          If Choice(1)=1
            Proc1
          Endif
          If Choice(1)=2
            Proc2
          Endif
        :  :  :
        :  :  :
        Endif

There is one crucial difference between the ON MENU command and the
above instructions. ON MENU is performed 50 times a second using
interrupts and does not affect the overall running of your program.
This means that your program can be doing something totally different
while the menus are being checked by the system.

Whenever the user selects a menu item the required procedure will be
immediately executed with no further ation on the part of your program.
Your procedure can then use the CHOICE command to find which option has
been chosen and perform the appropriate action.

  After the procedure has concluded, your program will be returned to
the instruction following the ON MENU call. Here's an example:

        Menu$(1)="Action" : Menu$(1,1)="Count" : Menu$(1,2)="Quit"
        Menu On : Rem Activate menu
        On Menu Proc ACTION
        On Menu On : Rem Activate On Menu command
        Do
          X$=Inkey$ : If X$<>"" Then Print X$;: Inc W
        Loop
        Procedure ACTION                                                   218
          Shared W
          If Choice(2)=1
            Locate 0,0 : Print "You typed ";W;" letters" : W=0
            On Menu On : Rem Initialise menus
          Endif
          If Choice(2)=2 Then Edit
        End Proc

There are a couple of important points to note about this example.
Firstly, see how the on menu sequence is activated using the ON MENU ON
command. This *must* be called after the menu handling procedure has
finished as it's needed to restart the menuing system. Also note the
use of INKEY$ rather than INPUT. The INPUT command will halt the menu
checks while you are entering a line. All other commands can be used
without problems, including WAIT, WAIT VBL and WAIT KEY. For a further
example see EXAMPLE 16.4



               ON MENU GOSUB (automatic menu selection)

ON MENU GOSUB label1 [,label2,...]

Enters one of a list of subroutines depending on the option which has
been selected by the user. Once you've called this command and created
your subroutines, the menus will be checked automatically 50 times a
second.

  Note that each title on the menu line is handled by its own
individual subroutine. This differs from its AMIGA Basic equivalent
which controls the entire menu with just a single routine.

  After using this command you should activate the menuing system with
a call to the ON MENU. The menus must be reinitialised in this way
before jumping back to the main program with RETURN. Also note that
label *MAY NOT* be replaced by an expression as the label will only be
evaluated once when the program is run.



                ON MENU GOTO (automatic menu selection)

ON MENU GOTO label1 [,label2,...]

This command has now been superceded by the more powerful ON MENU PROC
and ON MENU GOSUB instructions. It's intended to provide compability
with programs written in STOS Basic. WHen ever a menu is selected, the
program wlil jump to the appropriate label.



                ON MENU ON/OFF ([de]activate automatic
                            menu selection)
ON MENU ON

Activates the automatic menuing system created by the ON MENU
PROC/GOSUB/GOTO commands. After a sub-routine has been accessed in this
way, the system will be DISABLED. So it's vital to reactivate the
system with ON MENU ON before returning to the main program.

ON MENU OFF

This temporarily freezes the automatic menuing system. It's useful when
your program is executing a procedure which needs to be performed
without interruptions - such as loading and saving information to the
disc. The menus can be reactivated using ON MENU ON.



            ON MENU DEL (dlete the labels used by ON MENU)                 219

ON MENU DEL

This erases the internal list of labels or procedures created by the ON
MENU commands. You can now redirect your menus to another part of your
program using a further call to ON MENU. WARNING! Only use this command
after you've deactivated the menus with ON MENU OFF.


Keyboard shortcurs
------------------
Despite the undoubted appeal of menus, some users prefer to call up the
options of a program straight from the keyboard. Althought menus are
certainly easy for beginners, once you've familiarised yourself with a
program it can be much faster to call up an option from the keyboard.

  AMOS Basic allows you to assign a keyboard shortcut to any of your
menu items. These keystrokes are interpreted exactly as if the user had
accessed the equivalent option from the menu. They can be used with any
of the AMOS Basic menuing commands, including ON MENU.



                MENU KEY (assign a key to a menu item)

MENU KEY(,,) TO c$
MENU KEY(,,) TO scan[,shift]

This allows you to assign any key to any item in a previously defined
menu. The only restriction is that item you have specified must be at
the bottom level of our menu. So you can't use a shortcut to select a
sub menu as each command must correspond to a single option in the
menu.

  c$ is a string containing a single character which is to be assigned
to the menu option. Any additional characters in the string will be
ignored.

  Each key on the Amiga's keyboard is assigned its own individual
scancode. By using this code you can assign keys to a menu which have
no Ascii equivalents. Here is a list of scancodes which can be used
with your menus.

        Scancode  Keys
        --------  ----
        80 - 89   Function keys F1-F10
           95     Help
           69     Esc

"shift" is an optional bitmap which allows you to check for control key    220
combinations such as ALT+HELP or CONTROL+D. The format of "shift" is:

        Bit  Key Tested      Notes
        ---  ----------      -----
         0   Left SHIFT      Only one shift key can be tested at a time
         1   Right SHIFT
         2   Caps Lock       Either ON or OFF
         3   CTRL
         4   Left ALT
         5   Right ALT
         6   Left AMIGA      C= key on some keyboards
         7   Right AMIGA

Note that if you set more than a single bit in this pattern, you'll
have to press several keys simultaneously to call up your menu item.
Any of these short-cuts can be deactivated by using MENU KEY with no
parameters. For example:

        Menu Key(1,10)

With the help of MENU KEY command, adding shortcuts to a menu is a
trivial operation, so you are strongly recommended to include them as
standard in your programs. Here is an example that checks for the
Amiga's 10 function keys:

        Menu$(1)=" Function Keys "
        For A=1 To 10
          OPT$=" F"+Str$(A)+" "
          Menu$(1,A)=OPT$
          Menu Key(1,A) To 79+A
        Next A
        Menu On
        Do
          If Choice Then Print "You pressed function key ";Choice(2)
        Loop


Menu control commands
---------------------


                       MENU ON (activate a menu)

MENU ON [bank]

Activates a menu which has been previously defined in your program. The
menu will be displayed when the user next presses the right mouse
button, and the options can be selected in the usual way. If a "bank"
number is included with the instruction, then the menu will be taken
from the appropriate memory bank. See MAKE MENU BANK for more details.



               MENU OFF (temporarily deactivate a menu)                    221

MENU OFF

THis is the opposite of the MENU ON command. It temporarily freezes the
action of the entire menu. The menu can be restared at any time using
the MENU ON command.



               MENU DEL (delete one or more menu items)

Erases the selected menu from the Amiga's memory and restores the space
to the rest of your program. There are two possible formats.

MENU DEL

Erases the enitre menu. WARNING! This command is irrevocable!

MENU DEL(,,)

Deletes just a section of the menu. The (,,) parameters contain a list
up to eight values separated by commas. These indicate the precise
position of the item in the menu hierarchy. For example:

        Menu Del(1) : Rem Erase title number 1
        Menu Del(1,2) : Rem Erase option 2 of title 1



                MENU TO BANK (save the menu definitions
                           in a memory bank)

MENU TO BANK n

This instruction allows you to save an entire menu tree into memory
bank n. If bank n already exist, you'll get a "bank already reserved"
error.

  Once you've stored a menu in this way, it will be saved automatically
along with your Basic program. By storing your menu definitions in a
memory bank, you can reduce the size of your program listings
significantly. This will free valuable space in the editors memory, and
will allow you to write longer Basic programs using exactly the same
amount of memory.



               BANK TO MENU (restores a menu definition
                         saved in a menu bank)

BANK TO MENU n

Sets up a menu definition from menu data stored in bank number n. You
menu will be restored to exactly the same state as it was originally
saved. If the menu is complex, this process may take a little time. To
activate your ne menu call the MENU ON instruction.



                    MENU CALC (recalculate a menu)                         222

MENU CALC

One of the nicest features of AMOS menus is that they can be easily
changed during the course of a program. After you've created your
initial definition you can add new items and replace existing options
as well.

  Al your menu items are automatically repositioned when the menu is
selected with the right mouse button. If your menus are extremely large
this may takek a little time. MENU CALC allows you to perform this
process at the most appropriate point in your program, and avoid
unnecessary and unwanted delays.

  Note that in order to stop the user calling the menu while it's being
changed, you are strongly adviced to freeze the menus with MENU OFF at
the start of your procedure. The menu can then be safely restarted
using the MENU ON command after you've finished. Evolving menus are
particularly useful for adventure games as each location can have its
own individul menu options which can be updated depending on the
player's actions.



Embedded menu commands
======================
Any menu string can optionally include a powerful set of embedded
commands which allow you to customize the appearance of your menus to
an incredible degree. The list of commands in enclosed between sets of
round brackets () and individual instructions are separated using
colons ":". For example:

        Menu$(1)="(Locate 10,10 : Ink 1,1) Hello"

Each instruction consists of just two characters which can be in either
upper or lower case. Anything else will be ingnored completely. Most
commands also require you to input one or more commands. These numbers
*must never* make use of expressions as these are not evaluated. The
commands are listed below.

  Note: In the syntax the two important characters which make up the
command are in upper case and highlighted bold.



                           BOB (draw a bob)

BOb n
--
The BOB command draws a bob number n at the current cursor position. No
accound is taken of the hot spot of the bob. All coordinates are
measured relative to the top left corner. Also note that colour zero is
usually treated as transparent. This may be changed using the NOMASK
command from AMOS Basic. For example:

        Load "AMOS_DATA:Sprites/Octopus.abk"
        Menu$(1)="(Bob 1) 1":Menu$(1,1)="(Bob 2) 2"
        Menu$(1,2)="(Bob 3) 3"
        Menu On : Wait Key



                          ICON (draw an icon)

ICon n
--
Draws icon # n at the current cursor position. Note that unlike bobs,
colour zero is NOT normally transparent. See the Basic MAKE ICON MASK
for more details.



                   LOCATE (move the graphics cursor)                       223

LOcate x,y
--
Tis command moves the graphics cursor to coordinates x,y measured
relative to the top left corner of the menu line. Note that after an
instruction the graphics cursor will always be positioned at the bottom
right of the object which has just been drawn. These coordinates will
also be used to determine the location of any further items in your
menu like so:

        Menu$(1)="Example ":Menu$(1,1)="Locate (Lo 50,50) in action "
        Menu$(1,2)="Guess my coords"
        Menu On : Wait Key



                    INK (set Ink and Paper colours)

INk n,value
--
The INK command assigns the colour indexes to be used for the PEN,
PAPER and OUTLINE colours, Here's a list of the various possibilities:

        n       Effect
        -       ------
        1       Set text PEN colour
        2       Set PAPER colour
        3       Set OUTLINE colour



                           SFONT (set font)

SFont n
--
SFont sets the current font to *graphics* font number n. This will be
used in all future menu items. NOte that you MUST call GET FONTS before
this instruction is executed, otherwise it can only use the two rom
fonts. See EXAMPLE 16.5.



                        SSTYLE (set font style)

SStyle n
--
This command sets the style of the current font to n which is a
bit-pattern in the following format:

        Bit    Effect
        ---    ------
         0     Underline
         1     Bold
         2     Italic



                          LINE (draw a line)                               224

LIne x,y
--
The LINE command draws a line from the current cursor position to the
graphics coordinates x,y. See EXAMPLE 16.6



                       SLINE (set line pattern)

SLine p
--
Sets the line style used in all subsequent LINE comands to the bit
pattern held in p. Since there is no expession evaluation, this pattern
should always be converted into decimal notation before use. A simple
demonstration of the possible line styles can be found in EXAMPLE 16.7.



                           BAR (draw a bar)

BAr x,y
--
This draws a rectangular bar from the current cursor coordinates to
x,y. See EXAMPLE 16.8.



                 OUTLINE (enclose bar with an outline)

OUtline flag
--
Draws a border in the current outline colour (ink 3) around all
subsequent bars. A value of one activates the border and 0 removes it.



                       ELLIPSE (draw an ellipse)

ELlipse r1,r2
--
Draws an oval with radii r1 and r2 at the current cursor coordinates.
To draw a circle, set r1 equal to r2. See example 16.9.



                        PROC (call a procedure)                            225

PRoc NAME
--
The PROC instruction allows you to call any AMOS Basic procedure
directly within a menu line. The called procedure must NOT include
paramters, otherwise a syntax error will be indicated.

  This command allows you to customize the menu precisely to your own
needs without having to limit yourself to the available menu commands.
In order to exploit these features, you'll need to understand a little
bit of theory.

  At the start of your procedure the following values are held in the
68000's processor registers.

        Dreg(0)         X-Coord

  This holds the graphical X coordinate of the top left corner of the
  current menu item. Don't draw your gfxs over the part of the screen
  to the left of this point as this will confuse the menu redrawing
  process and may lead to unwanted effects.

        Dreg(1)         Y-Coord

  Contains the Y coordinate of your menu item. As with the X coordinate
  you should always limit your drawing operations to the region below
  this point to avoit possible errors.

        Dreg(2)         Status of drawing operations

  This register holds the current status of the menu operations. If it
  contains a value of 0 (false) the menu item is being drawn. In this
  case you will need to load Dreg(0) and Dreg(1) with the coordinates
  of the bottom right corner of your menu zone and return from the
  procedure immediately. If Dreg(0) is -1 (true) you are free to
  perform your gfx operations used by your procedure. After you have
  finished you should return the coordinates of the bottom right corner
  of your item in Dreg(0) and Dreg(1) as before.

        Dreg(3)         Status of menu item

  D3 is loaded with a value of -1 if the menu is highlighted and the
  first menu string is displayed, otherwise it will contain a value 0.

        Dreg(4)

  D4 is set to TRUE when the menu branch is initially opened.

        Areg(1)         Address of reserved zone

  This is the address of the zone created with RESERVE. It's used to       226
  allow several procedures to communicate with each other. See RESERVE
  for more details.


  The general structure of a menu procedure is:

        Procedure ITEM
          If DREG(2)
            X=DREG():Y=DREG(1)
             ...draw the item...
          Endif
          DREG(0)=BX
          DREG(1)=BY
        End Proc

The dimensions of the menu item as displayed on the screen are set
using the coordinates BX and BY. These MUST be loaded into registers D0
and D1 before leaving your procedure as they are needed to create the
final menu bar.

  While inside your procedure you can perform most AMOS instructions
including other procedures. But some instructions are absolutely
forbidden! If you use these commands, you won't get an error message
but your AMIGA may crash unexpectedly!

 * NEVER change the current screen inside a menu.
 * Don't set or reset a screen zone
 * Avoid using instructions such as WAIT, WAIT KEY, INPUT or INKEY$
 * Disc operations are absolutely forbidden!
 * Any error trapping in your procedure will be ignored.

  Used with caution, the PROC command can procedure some mind-blowing
effects. For a demonstration, load EXAMPLE 16.10.



                     RESERVE (reserve a local data
                         area for a procedure)
REserve n
--
Reserves n bytes of memory for this menu item. This area can be
accessed from within your menu procedure using the address held in
AREG(1). The data area you have created is common to all the strings in
the current menu object. It can be used to exchange parameters between
the various procedures called by a menu item.



             MENU CALLED (redraw a menu item continually)

MENU CALLED(,,)

Automatically redraws the selected menu item 50 times a second whenever
it's displayed on the screen. It's usually used in conjunction with a
menu procedure to generate animated menu items which change in front of    227
your eyes.

  In order to make use of this function, you first need to define a
menu procedure, using the principles outlined above. Then add a call to
this procedure in the required title strings using an embedded
MENU CALL. When the user displays the chosen item, your procedure will
be repeatedly accessed by the menuing system.

  Since your procedure will be called 50 times a second, it should
obviously return back to the menu as quickly as possible. This will
allow enough time for the rest of the menu to be succesfully updated.

  Also note that your embedded procedure can safely animate your item
using either bobs or sprites. However, as the menu items are NOT double
buffered, your bobs may flicker slightly on the screen. So it may be
better to use computed sprites for this purpose instead. Another
approach is to draw your display with the standard AMOS graphics
commands. An example of this can be seen in EXAMPLE 16.11.



               MENU ONCE (turns off automatic redrawing)

MEUN ONCE(,,)

Turns off the automatic updating system started using the MENU CALLED.


Alternative menu styles
=======================
Normally the titles of a menu are displayed as a horizontal line and
the options are arranged below it in a vertical menu bar. If you want
to create something a little unusual, you can change the format of each
level of your menu using the following three instructions:



                       MENU LINE (display a menu
                    as a horizontal line of items)
MENU LINE level
MENU LINE(,,)

Displays the menu options at the requested level in the form of a
horizontal line. This menu line starts from the left-hand corner of the
first title and stretches to the bottom right corner of the last.

MENU LINE level

Defines the menu style of an entire level of your menu. This sould only
be called during your menu definitions.

MENU LINE (,,)

Normally one would only use the "level" version for this command.
Setting individual items to Line and Bar can give bizarre results, but
this may be useful for something!



              MENU TLINE (display a menu as a total line)                  228

MENU TLINE level
MENU TLINE(,,)

Displays a section of the menu as a "total line" stretching from the
very left of the screen to the very right. The entire line will be
drawn even when the rist item is in the middle of the screen.

  "level" is a number ranging from 1 to 8 which specifies the part of
the menu to be affected. This is the standard form of the instruction,
and should be called during your menu definitions as otherwise it will
have no effect.

  You can also change the appearance of a menu after it has been vrated
using a second form of this command. For example,

        Menu Line(1,1) : Rem Displays menu 1,1 as a line.



                  MENU BAR (display a section of the
                            menu as a bar)

MENU BAR level
MENU BAR(,,)

This displays the selected menu items in the form of a vertical bar.
The width of this bar is automatically set to the dimensions of the
largest item in your menu.

  "level" is a number which indicates which part of the current menu
definition is to be affected. As a default this option is used for
levels 2 to 8 in your menu. Note that this form of the MENU BAR
instruction may only be used during your programs initialisation phase.

  (,,) is a list of parameters which allow you to change the style of
your menus once they've been installed. Here's an example of Menu Bar
and Menu Tline:

        FLAG=0
        SET_MAN
        Do
          If Choice and Choice(1)=2 And Choice(2)=1 Then ALTER
        Loop
        Procedure SET_MEN
          Menu$(1)=" Bar Demo " : Menu$(2)=" Select Below "
          Menu$(1,1)=" I do nothing! "
          Menu$(2,1)=" Yes, press on me! "
          Menu On
        End Proc
        Procedure ALTER
          Shared ALTER
          Menu Del
          If FLAG=0 Then Menu Bar 1 : Flag=1 Else Menu Tline 1 : Flag=0
          SET_MEN
        End Proc



                  MENU INACTIVE (turn off menu item)                       229

MENU INACTIVE level
MENU INACTIVE(,,)

As its name suggests, MENU INACTIVE deactivates a series of options in
your menu. Any subsequent attempts to select these items will be
completely ignored. "level" allows you to deactivate an entire section
of the menu and you can also deactivate individual menu options with
the parameters (,,). These indicate the precise position of your item
in the current menu hierarchy.

  Note that the menu items you've turned off with the instruction will
be immediately replaced by the INACTIVE$ string you specified during
your original menu definition. If this was omitted, any unavailable
menu options will be shown in italics.



                  MENU ACTIVE (activate a menu item)

MENU ACTIVE level
MENU ACTIVE(,,)

Simply reverses the effect of a previous MENU INACTIVE command. After
you've called this instruction, the selected options will automatically
redisplayed using their original title strings.


Moveable menus
==============
AMOS menus can be displayed at any point on the screen. Menus can be
moved either explicity by your program or directly by the user.



            MENU MOVABLE (activate automatic menu movement)

MENU MOVABLE level
MENU MOVABLE(,,)

Informs the menuing system that the menu items at "level" may be moved
directly by the user - this is the default.

  The second form of this command allows you to set the status of each
individual item in the menu. The parameters between the brackets can
indicate any position in the menu hierarchy.

  Any menu may be repositioned by moving the mouse pointer over the
FIRST item in the menu and pressing the left mouse button. A
rectangular box will now appear around the selected menu item, and this
may be moved to nay point on the current screen. When you release the
left button the menu will be redrawn at the new position along with all
the associated menu items.

  Note that this command does not allow you to change the arrangement
of any items below this level. If you want to manipulate the individual
menu options you'll need to use a seaparate MENU ITEM command. See
EXAMPLE 16.12 for a demonstration of this system.



                  MENU STATIC (fix a menu into place)                      230

MENU STATIC level
MENU STATIC(,,)

Defines the menu at "level" to be immoveable by the user. One problem
with moveable menu is that the amount of the memory they consume will
change during the course of a program. If your menus are particularly
large, or if memory is running tight, this can cause real problems as a
single careless action by the user will abort your program with an
"out of memory" error. With the help of the MENU STATIC command you can
avoid this difficulty completely.



                        MENU ITEM MOVABLE (move
                       individual menu options)

MENU ITEM MOVABLE level
MENU ITEM MOVABLE(,,)

This command is similar to MENU MOVABLE except that it allows you to
re-arragne the various options in a particular level. So all the items
in a menu bar may been individually repositioned by the user.

  Normally it's illefal to move the items outside the current menu bar,
but this can be overridden using the MENU SEPARATE command.

  In order for the menu items to be moveable, the WHOLE menu bar must
also be moveable. So if you fix the MENU into palce with MENU STATIC,
this command will have no effect. Additionally you can't move the first
item in the menu bar as this will move the entire line. Another side
effect is that moving the last menu item will permanently reduce the
size of your menu bar. There are two possible solutions:

 * Enclose your entire bar with a rectangular box like so:

        Menu$(1,1)=,,,"(Bar 40,100)(Loc 0,0)"

Where MENU$(1,1) is the first item in your current bar.

 * Set the last item into place with MENU ITEM STATIC.



                  MENU ITEM STATIC (static menu item)

MENU ITEM STATIC level
MENU ITEM STATIC(,,)

This command locks one or more menu items firmly into place and is the
default setting.



             MENU SEPARATE (separate a list of menu items)                 231

MENU SEPARATE level
MENU SEPARATE(,,)

Tells AMOS to separate all the items in the current level. Each item in
your menu istreated completely independently from the previous one. If
you haven't defined a background string, each item will be offset by
two pixels from the one above. This creates an attractive stepped
effect which can be removed by editing the menu with the MENU
Accessory.

  The optional parameters to this instruction allow you to split a menu
bar at any point in the line. Once you've separated an item it will be
affected by the MENU MOVABLE commands rather than ITEM instructions.



                 MENU LINKED (link up a set of menus)

MENU LINKED level
MENU LINKED(,,)

This links one or more menu items together. It's the opposite of the
MENU SEPARATE instruction.



              =MENU X (return the graphical X coordinate
                           of an menu item)

x=MENU X(,,)

The MENU X function allows you to retrieve the position of a menu item
relative to the previous option on the screen. You can use this
information to implement powerful menus such as the one found in
EXAMPLE 16.13.



              =MENU Y (return the graphical Y coordinate
                            of a menu item)

x=MENU Y(,,)

Returns the Y coordinate of a menu option. note that all coordinates
are measured relative to the previous item. So this is NOT a standard
screen coordinate!


Moving a menu within a program
==============================


             MENU BASE (move the starting point of a menu)

MENU BASE x,y

This command moves the starting point of the first level of your menus
to the absolute csreen coordinates x,y. All subordatine menu items will
be displayed at their curent positions relative to the top of your
menu. See EXAMPLE 16.14 for a demonstration of the MENU BASE command in
action.



                        SET MENU (move a menu)                             232

SET MENU (,,) TO x,y

Sets the coords of the top left corner of a menu item. These
coordinates are measured relative to the previous level. The starting
point for the entire menu (coords 0,0) may be set with the MENU BASE
command.

  All the lvels of the menu below your menu wlil also be moved by this
instruction. Their relative positons will be unchanged. SInce x,y can
be negative numbers, it's possible to arrange the items in a menu bar
in the form of a control panel - see EXAMPLE 16.15.

Displaying a menu at the cursor position

             MENU MOUSE (display the menu under the mouse)

MENU MOUSE ON/OFF

The MENU MOUSE features automatically display all menus starting from
the current position of the mouse cursor. The mouse coordinates are
added to the MENU BASE to get the final position, so it's possible to
place the menu a fixed distance away from the mouse pointer if
required. See EXAMPLE 16.16.

17: SOUND AND MUSIC
The Amiga's sound system is capable of generating stereo sound effects
which would have been unheard of just a few years ago. The results are
impressive even through your TV speaker, but when you connect your
Amiga to a Hi-Fi, the sounds can actually shake your room!

  As you would expect from AMOS, we've come a long way since the humbe
BEEP command. In fact, we've provided everything you need to
incorporate mind-blowing sound effects in your own games. All the AMOS
sound commands are performed independently of your Basic programs. So
your soundtracks can be played continuously, without affecting the
quality of the game-play in the slightest.

  Samples may be created using any of the available sampling cartridges
and can be replayed with a simple SAMPLAY instruction. Each sample can
be output in a variety of speeds, and may be looped repeatedly. It's
even possible to play a sample as a musical note.

  Music can be converted over from a separate package such as SONIX,
SOUNDTRACKER or GMC. The AMOS Music system is intelligent and will
automatically stop when a sound is played through the current channel,
thus allowing you to effortlessly combine both samples and music in the
same sound channel, without the risk of unwanted interference effects.

  Each song can incorporate up to 256 separate instruments; the only
limit to the number of songs is the amount of available memory. In
order to keep the memory overhead down to an absolute minimum, all
tunes are built up of a number of separate patterns. Once a pattern has
been created, it can be accessed anywhere in your music using just a
couple of bytes. By defining just a few key patterns, you can therefore
create dozens of different tues without running short of memory.

  The best thing about the AMOS music system however, is that it's
expandable. The entire source code is supplied on the data disc for you
to examine or change. So you won't be left out in the cold by any
future developments on the Amiga's music scene.


Simple sound effects
====================
We'll start off with a run down of the built-in sound effects included
in AMOS Basic. These are the AMOS equivalent to the Amiga Basic BEEP
command.



          BOOM (generate a noise sounding like an explosion)

BOOM

Kapow! You're dead! Use BOOM to add the appropriate stereo sound effect
in your games. Traditionally this type of "White Noise" as been
extremely difficult on the Amiga, but AMOS uses a clever interrupt
system to create a realistic explosion effect. Example:

        Boom : Print "You're DEAD!"



               SHOOT (create a noise like a gun firing)

SHOOT

This command generates a simple gunshot effect. Like BOOM, SHOOT does
not halt your program in any way. So if you're firing several
successive shots, you may wish to add a small delay using WAIT.

        Shoot : Wait 6 : Shoot : Print "You're DEAD!"



                       BELL (simple bell sound)                            234

BELL [f]

BELL produces a pure tone with frequency f. f sets the pitch of the
note, from 1 (very deep) to 96 (very high).


Sound channels
==============
The Amiga's hardware can effortlessly play up to four different sounds
simultaneously. This allows you to add attractive harmonics to your
sound effects.

  Each sound can be output through one of four VOICES numbered from
0 to 3. You can think of these voices as a separate instruments which
can independently play their own sequence of notes, samples or music.
All four voices are internally combined to generate the final sound you
hear through your speaker system.

  The AMOS sound instructions will happily play your sounds using any
arrangement of voices you like. All AMOS sound commands use a standard
way of entering your voice settings. Each voice is assigned a
particular bit in a VOICE parameter like so:

        Bit 0 -> Voice 0
        Bit 1 -> Voice 1
        Bit 2 -> Voice 2
        Bit 3 -> Voice 3

To activate the required voices, set the appropriate bits to 1. Here's
a list of common values to make things a little easier

        Value  Voice used  Effect
        -----  ----------  ------
         15     0,1,2,3    Uses all four voices
          9     0,3        These voices are combined together and
                           output to the left speaker.
          8     3
          6     2,4        Played through the RIGHT speaker.
          4     2
          2     1
          1     0

In order to do justice to the resulting sound effects, you'll almost
certainly need to connect your Amiga to a Hi-Fi system of some sort.
Most TVs are just not capable of reproducing the full range of sounds
which can be generated by the Amiga's amazing hardware.



                   VOLUME (change the sound colume)                        235

VOLUME [v,] intensity

VOLUME changes the volume of the sounds which are to be played through
one or more sound channels.

  "intensity" refers to the loudness of this sound. It can normally
range from 0 (silent) to 63 (maximum). As a default, the volume is set
to the same intensity for all four of the available voices. THe new
volume will be used for all future sound effects, including music.

  The v parameter lets you change the volume of each voice
independently. v now indicates which combination of voices are to be
regulated. This second option is only used by the sound effects. It has
no affect on any music you're playing. The voices are selected using a
bit amp in the standard format, with each bit representing state of a
single sound channel. If the bit is set to 1, then the volume of this
voice will be changed, otherwise it will be unaffected. Examples:

        Volume %0001,63 : Boom : Wait 100
        Volume %1110,10 : Boom : Wait 50
        Play 40,0 : Wait 30
        Volume 50 : Play 40,0


Sampled sound
=============
If you had to generate all the sound effects you need, directly inside
your computer, you would be faced with an impossible task. In practive,
it's often much easier to take a real sound from an external source,
such as a tape recorder, and convert it into a list of numbers which
can be held in your computer's memory.

  Eacn number represents the volume of a particular sample of the
sound. By rapidly playing these values back through the Amiga's sound
chips, you can recreate a realistic impression of the original sound.
This technique forms the basis of the sampled sound effects found in
most modern computer games.

  If you want to create your own samples, you'll be forced to buy a
separate piece of hardware known as a SAMPLER CARTRIDGE. Although these
cartridges are fun, they're certainly not essentia. AMOS Basic is
perfectly capable of playing any existing sound sample, without the
need for any expensive add-ons.

  Currently there are hunderds of sound effects available from the
public domain (PD), covering the vast majority of the effects you'll
need in your games. We've even included a selection of useful samples
on the AMOS data disc for you to experiment with.



                  SAM PLAY (play a sound sample from
                         the AMOS sample bank)

SAM PLAY s
SAM PLAY v,s
SAM PLAY v,s,f          The SAMP PLAY instruction plays a sampled sound
                        straight through your loudspeaker system. All
samples are normally stored in memory bank number 5, but this may be       236
freely changed using the SAM BANK command.

  s is the number of the sample bank which is to be played. There's no
limit of the samples you can store in a bank other than the available
memory. If you want to use your own samples with this instruction,
you'll need to incorporate them into an AMOS memory bank. Full details
can be found towards the end of this section.

  v is a bit-map containing a list of voices your sample will use. As
usual, there's one bit for each possible voice. To play your samples
through the required voice, simply set the relevant bit to 1.

  f holds the playback speed of your sample, measured in hertz. This
specifies the number of samples which are to be played each second.
Typical sample speeds range from 4000, for noises such as explosions,
to 10000 for recognisable speech effects. By changing the playback
rate, you can freely adjust the pitch of your sound over a large range.
So a single sample can be used to generate dozens of different sounds.
Example:

        Load "AMOS_DATA:Samples/Sample_Demo.abk"
        For S=1 To 11
          Locate 0,0 : ? "Playing sample ";S
          Sam Play S
          Locate 0,24 :Centre "<Hit a key to continue>" :Wait Key :Cline
        Next S
        Wait Key
        Sam Play 1,11 : Wait 5 : Sam Play 2,11
        Wait key
        Sam Play 1,1,2000
        Wait Key
        Sam Play 1,1,15000

A further demonstration of this command can be found in EXAMPLE 17.1



                  SAM BANK (change the current bank)

SAM BANK n

Assigns a new memory bank to be used for your samples. All future
SAM PLAY instructions will now take their sounds directly from this
bank.

  It's possible to exploit this feature to hold several complete sets
of samples alongide each other. You can then between these samples at
any time, with just a simple call to the SAM BANK.



                  SAM RAW (play a sample from memory)

SAM RAW voice,address,length,frequency

Plays a raw sample stored anywhere in the Amiga's memory. "voice" is a     237
bit-pattern in standard format which specifies the list of voices your
sample is to use. Each bit in the pattern selects a single channel to
be played (see sound channels).

  "address" holds the address of your sample. Normally, this will refer
to the inside of an existing AMOS memory bank. "length" contains the
length of the sample you wish to play. "frequency" indicates the sample
speed to be used for the playback (in samples per second or Hz). This
may be very different to the rate at which the sample was originally
recorded.

  SAM RAW lets you play standard Amiga samples straight through your
loudspeaker, without the need to create a special memory bank (see
Creating a sample bank). It's now your responsibility to manage your
samples in memory, and enter the sample parameters by hand. SAM RAW is
great for browsing through files from your disc collection. Use BLOAD
to hold a file in a bank and then use SAM RAW to play the data. With
luck you should come across some interesting sounds. Examples:

        Reserve As Work 10,55000
        Bload "Samples/Samples.abk",start(10)
        Sam Raw 15,start(10,length(10),10000



                      SAM LOOP (repeat a sample)

SAMP LOOP ON/OFF

The SAM LOOP directive informs AMOS Basic that all subsequent samples
are to be repeated continuously. Examples:

        Load "AMOS_DATA:Samples/Sampledemo.abk"
        Sam Loop On
        For S=1 To 11
          Locate 0,0 : Print "Playing sample ";S
          Sam Play S
          Locate 0,24 : Centre "<Hit a key to continue>":Wait Key :Cline
        Next S
        Sam Loop Off

This looping effect can be deactivated with a simple call to the
SAM LOOP OFF command.


Creating a sample bank
======================
If you're indenting to play your own samples using SAM PLAY, you'll
first need to load them into a memory bank. This can be achieved with
the SAMMAKER program supplied on the AMOS data disc.

  On start-up, SAMMAKER presents you with a standard AMOS file
selector. Enter the filename of the first sample to be stored in your
new bank, and press RETURN. If AMOS can't find the sampling rate,
you'll be asked to enter it directly. It doesn't really matter if you
make a mistake at this point, as you can safely replay your samples at
any speed you like.

  After a short delay, you'll be prompted for the next sample to be
installed into the bank. When you've reached the end of your samples,
type SAVE at the file selector to save your samples onto the disc.
You'll be automatically prompted for the destination filename of your
new bank. This can now be entered into AMOS Basic using the LOAD
command like so:

        Load "Sample.abk"
        Load "Sample.abk",6 : Rem Loads sample into bank #6.               238



Music
=====
The AMOS music system allows you to easily add an attractive backing
track to your games. Music can be created from a variety of sources,
including GMC, SOUNTRACKER or SONIX.

  In order to convert these musics into the special AMOS format, you'll
need to use one of the translation programs included on the AMOS data
disc. GMC music should have been saved using the SAVE DATA icon, as
this copies both the music and the instrument definitions into a single
large data file.



                     MUSIC (play a piece of music)

MUSIC n

The AMOS MUSIC command starts a piece of music from the music bank
(#3). This music will be played independently of your Basic program,
without affecting it in the slightest.

  Normally, it's possible to store several complete arrangements in the
same bank. Each composition is assigned its own individual music
number. The only exception to this rule is music created by GMC, which
only allows you to place one song in the bank at a time. Example:

        Load "MUSIC/Musicdemo.abk"
        Music 1

The AMOS music system is intelligent, and will automatically suspend
your music for the duration of any subsequent sound effects on the
current channel. When the sound has finished, your tune will be
restarted from its previous position. Up to three separate tunes can be
started at a time. Each new music command stops the current song, and
pushes its status onto a stack. Once the song has concluded, the old
music will commence from where it left off.



              MUSIC STOP (stop a single section of music)

MUSIC STOP

Halts the current piece of music. If another music is active, it will
be restarted immediately.



                    MUSIC OFF (turn off all music)

MUSIC OFF

THe MUSIC OFF command deactivates your music completely. In order to
restart it, you'll need to execute your original series of MUSIC
instructions again from scratch.



             TEMPO (change the speed of a sample of music)                 239

TEMPO s

TEMP modifies the speed of any tune which is currently being played
with the MUSIC command. s is the new speed, and can range from 1 (very
slow) to 100 (very fast). Not all instruments are capable of playing at
this maximum speed, however. The practical limit is closer to 50. For a
demonstration, place the AMOS data disc into the current drive and
type:

        Load "AMOS_DATA:Music/Musicdemo.abk"
        Music 1
        Tempo 35
        Tempo 5

Note that music created with GMC often contains labels which set the
tempo directly inside the arrangement. These labels will override the
tempo settings within AMOS Basic. So it's not advisable to use them in
your own music.



             MVOLUME (set the volume of a piece of music)

MVOLUME n

Changes the volume of the entire piece of music to intensity n (0-63).



                  VOICE (activate one or more voices
                         of a piece of music)
VOICE mask

Activates one or more voices of the music independently. Usually each
voice will contain its own separate melody which will combined through
your speakers to generate the eventual music.

  "mask" is a bit mask in the normal AMOS format which specifies which
voices you wish to play. Each bit represents the state of one voice in
the music. If it's set to 1, the voice will be played, otherwise it
will be totally unused.

        Load "AMOS_DATA:Music/Musicdemo.abk"
        Music 1
        For V=0 To 15
        Locate 0,0 : Print "Voice ";V
        Voice V
        Wait 100
        Next V
        Direct
        Voice %0001 : Rem Activate voice 0                                 240
        Voice %0010 : Rem                1
        Voice %1001 : Rem                3 and 0
        Voice %1111 : Rem                4



                        =VUMETER (volume meter)

s=VUMETER(v)

The VUMETER function tests voice v and returns the volume of the
current note which is being played by your music. s is an intensity
value between 0 and 63. v is the number of a single voice to be checked
(0-3).

  Using this function, you can make your sprites dance to a piece of
music! Load EXAMPLE 17.2 for a demonstration.

  Note there's also an AMAL version of this intruction which allows you
to create realtime VU meters using interrupts. See the section on the
VU command for more information.


Playing a note
==============


                          PLAY (play a note)

PLAY [voice,] pitch,delay

Plays a single note through the loudspeaker of your TV or Hi-Fi.
"pitch" sets the tone of this sound, ranging from 0 (low) to 96 (high).
Rather than just being an arbitrary number, each pitch is associated
with one of the notes (A,B,C,D,E,F,G). This can be seen from the
following table.

                           Octave
              --------------------------------
               0   1   2   3   4   5   6   7
        Note                Pitch
        ----  --------------------------------
        C     1   13  25  37  49  61  73  85
        C#    2   14  26  38  50  62  74  86
        D     3   15  27  39  51  63  75  87
        D#    4   16  28  40  52  64  76  88
        E     5   17  29  41  53  65  77  89
        F     6   18  30  42  54  66  78  90
        F#    7   19  31  43  55  67  79  91
        G     8   20  32  44  56  68  80  92
        G#    9   21  33  45  57  69  81  93
        A     10  22  34  46  58  70  82  94
        A#    11  23  35  47  59  71  83  95
        B     12  24  36  48  60  72  84  96

It should be apparent that the notes go up in a cycle of 12. This cycle    241
is known as an octave.

  The optional voice parameter allows you to play your notes through
any combination of the Amiga's four voices. As usutal it's a bit-map in
the format:

        Bit  Voice
        ---  -----
         0     0              Setting a bit to a value of 1 plays the
         1     1              relevant voice. "delay" sets the length
         2     2              of the pause between the play command and
         3     3              the next Basic instruction. This allows
                              you to play each note before preceding
                              the next one.

A delay of zero starts a note and immediately jumps to the next Basic
instruction. By playing several notes after another, you can easily
generate some attractive harmonic effects. Examples:

        Play 1,40,0 : Play 2,50,0
        Wait Key
        Play 1,40,15 : Play 2,50,15
        Do
          T=Rnd(96) : V=Rnd(15) : Play V,T,3
        Loop

PLAY is not limited to pure notes incidentally. It's also possible to
assign complex waveforms to the sound generator using the powerful WAVE
and NOISE commands.


Waveforms and envelopes
=======================


                     SET WAVE (define a waveform)

SET WAVE wave,shape$

The SET WAVE instruction provides you with the ability to define your
very own instruments for use with the AMOS Basic PLAY instruction. The
sound of yur instrument depends on the shape of a waveform held in the
Amiga's memory. This forms a template which is repeated to produce your
final note.

  "wave" is the number of the waveform you wish to define. Allowable
wave numbers start from 2 onwards. That's because waves zero and 1 are
already installed. Wave zero holds a random noise pattern for producing
explosion effects. Wave one is a smooth sine wave and generates the
pure tones used by the standard PLAY instruction.

  The shapes of your waveform are set using a list of 256 numbers which
are entered using the SHAPE$ parameter. Now look at the uppest diagram
in the AMOS4.PIC (file included with this manual packet).

         < picture AMOS4.PIC, the uppest diagram >                         242

  Each number represents the intensity of an individual section of the
waveform. This is equivalent to the height of just one point in the
diagram. Possible values for intensity range from -128 to 127. Since
AMOS strings are only capable of holding *positive* numbers (0-255),
you'll need to convert your negative values into a special internal
format before use. The required value can be calculated by simply
adding 256 to the negative numbers in your list.

  Here's a program which demonstrates how the triangular wave in the
previous diagram could be created in AMOS Basic

        S$=""
        For I=-128 To 127
          X=I : If X<0 Then Add X,256
          S$=S$+Chr$(X)
        Next I
        Set Wave 2,S$

Before playing your waveform you have to tell AMOS Basic which channels
are to be assigned to your wave. This can be achieved using the WAVE
command. Add the following line to the previous routine

        Wave 2 To 15 : For S=10 To 60 : Play S,10 : Next S

The Best way to reproduce the effect of a real instrument is to combine
several SINE waves together. An example of one of these sine waves can
be seen in the picture AMOS4.PIC:

         < picture AMOS4.PIC, the diagram in the middle >                  243

Adding several of these waves together, with different sizes and
separate starting points, produces waves in the following pattern:

         < picture AMOS4.PIC, the lowest diagram >

This generates the smooth harmonics needed for your notes. Here's an
example:

        SHAPE$="" : Degree
        For S=0 To 255
          V=Int((Sin(S)/2+SIN(S*2+45)/4)*128)+127
          SHAPE$=SHAPE$+Chr$(V)
        Next S
        Set Wave 2,SHAPE$ : Wave 2 to 15
        For N=10 to 60 : Play N,10 : Next N



          WAVE (assign a wave to one or more sound channels)

WAVE w To v

WAVE assigns wave number w to one or more sound channels. v contains a
bit-map in the standard format. If a bit in the pattern is set to 1
then the approrpriate voices are used by PLAY, otherwise they will be      244
completely unaffected.

  As a default, wave zero is reserved for the NOISE channel, and wave
one contains a sine wave. Here are some examples:

        Wave 0 To %0001
        Play 1,40,0
        Wave 0 To %1100
        Play 20,10
        Wave 1 To %1111
        Play 60,0


               NOISE (assign a noise wave to a channel)

NOISE TO voices

Applies a white noise effect (wave 0) to the selected voices. Load
EXAMPLE 17.3 for a demonstration.

  "voices" is a standard bit pattern. The first four bits represent the
four possible voices, starting from zero. NOISE is equivalent to the
command:

        Wave 0 To voices

Examples:

        Noise To 15
        Play 60,0
        Play 30,0



                       DEL WAVE (delete a wave)

DEL WAVE n

Deletes a wave which has previously been defined using SET WAVE. n is
the number of the wave, and starts at 2. It's impossible to delete the
built-in NOISE ans SINE waves using this instruction. After the wave
has been erased, all voices will be reset to the standard SINE wave
(default).



                  SAMPLE (assign a sample to a wave)

SAMPLE n TO voices

This is the most powerful cersion of all the wave commands. It assigns
a sample stored in the sample bank to the current wave. Play will now
take an instrument straight from the sample bank.

        Load "Samples/sample1.abk"                                         245
        Sample 1 To 15
        For I=20 To 50
          Play I,50
        Next I

As usual "voices" allows you to select a range of voices to be set by
the instruction. It's a standard bit-map; Bit 0 -> Voice 0   etc...

  Note!: The range of notes that a sample can be played with, depends
on its original recording rate. If a note is too high, AMOS may not be
able to play it at all. The acceptable range varies from a sample to
sample, but it's usually between 10 and 50.



                 SET ENVEL (create a volume envelope)

SET ENVEL wave,phase TO duration,volume

The SET ENVEL command smoothly changes the volume of a note while it's
being played. In the real world, sounds don't just sprint into
existence fully formed. They tend to evolve over a period of time,
according to a pattern known as the volume envelope. The shape of this
envelope varies depending on the type of instrument you are playing. A
typical example of one of these envelopes is shown in the picture
AMOS5.PIC.

         < picture AMOS5.PIC >

The sound is split up into four phases: Attack decay, sustain and
release. AMOS Basic allows you to define your envelopes using up to        246
seven separate steps. Each step represents a steady change in the
volume of the current note.

  "wave" is a number of the waveform which will be affected by this
instruction. It's possible to use any waveform you like for this
purpose, including the built-in NOISE and SINE generators.

  "phase" holds the number of the particular phase which is to be
defined, ranging from 0 to 6.

  "duration" specifies the length of the current step in units of a
50th of a second. This determines the apparent speed of the volume
change to be generated in this phase.

  "volume" specifies the volume which is to be reached by the end of
this phase. Allowable volume levels range from 0-63.

  It's important to understand that this volume is relative to the
intensity you've previously st with the VOLUME command. So even if the
note is quiet, the shape of the envelope will be perfectly reserved.
Now for some examples:

        Set Envel 1,0 To 200,63 : Rem Sets the 1st step.
        Play 40,0

As you can hear, the volume of your sound starts from zero, and
increases to a maximum intensity during the length of the note. Now
let's try defining something a little more complicated.

        Set Envel 1,0 To 15,60
        Play 40,0 : Wait Key
        Set Envel 1,1 To 1,50
        Play 40,0 : Wait Key
        Set Envel 1,2 To 10,50
        Play 40,0 : Wait Key
        Set Envel 1,3 To 50,0
        Play 40,0

Finally, here's an example of a NOISE envelope:

        Noise To 15
        Set envel 0,0 To 1000,30
        Play 40,0
        Wait Key
        Music Off

Don't confuse waves and envelopes. A wave sets the frequency components
of your notes, whereas an envelope simply changes their volume
according to a set pattern.


Speech
======
Your Amiga is supplied with a powerful speech synthesizer program which
can be found on the standard Workbench disc. With the help of this
routine, your AMOS programs can be made to speak. Speech is especially
userful in education, as many yound people will respond far better to
the spoken word than to boring text.

  One word of caution though. Since the narrator package is independent
of AMOS Basic, we can't attest to its absolute reliability. You're
unlikely to encounter any serious problems, but it's well worth
treating it with a littlle care.



                         SAY (speak a phrase)                              247

SAY t$[,mode]

The SAY command is incredibly easy to use. Enter your text in normal
English, concluding your phrase with a punctuation mark such as full
stop. SAY will now translate your words into an internal format and
speak them directly through your loudspeaker. Example:

        Say "AMOS Basic can really speak"

The first time you use this instruction, the narrator.device will
automatically be loaded from disc. So it's vital to ensure that an
appropriate disc is placed in the current drive before using this
system, as otherwise you may get an Intuition style requester box.

  "mode" toggeles between two separate speech modes. As a default, your
program will wait for the duration of the speech, and any music or
sound effects will be temporarily suspended. Setting "mode" to a value
of one activates multitasking system which allows you to output your
speech whilst AMOS is executing your program. Inevitably, this will
slow down your basic routines Considerably. To return your speech back
to normal, set mode to zero.

  If the narrator system cannot understand what you are attempting to
speak you won't get an error messagel, but the command will be
automatically aborted. Also note that the narrator can occasionally get
slightly confused with very short sentences. Sometimes the remainder of
the previous phrase is tagged to the end of the current voice. The
problem can be solved by simply adding a list of spaces to the end of
your text. These will wipe out the unwanted speech data.



                     SET TALK (set speech effects)

SET TALK sex,mode,pitch,rate

This allows you to change the type of voice which will be used by the
SAY command. "sex" chooses between a male (0) or female (1). In all
honesty, it's not a particularly realistic rendition. Better effects
can be created by simply increasing the frequency of the voice using
the pitch parameter.

  "mode" adds a strange rhythmic pattern to the voice. This can be
activated by setting "mode" to a value of 1.

  "pitch" changes the frequency of the voice, from 65 to 320.

  "rate" specifies the speed, measured in the words per minute (40-400).   248

  Any of the above parameters can be omitted if required. Providing you
keep the commas in their normal positions, you can change any set of
options independently.



Filter effects
==============


                   LED (activate a high pass filter/
                           change power led)

LED ON/OFF

The LED command has two completely separate actions. Not only does it
toggle the POWER led on your Amiga's console (in KickStart versions
1.3 just makes the led a little darker), but it also controls a special
high pass filter.

  The filter changes the way high frequency sounds are treated by the
system. Normally, these sounds are filtered out so as to avoid the risk
of unwanted distorion effects. Unfortunately, this robs many percussion
instruments of their timbre. By turning off the filter, you can
recapture the essential quality of many instruments.








                           18: THE KEYBOARD                                249
                      --------------------------

AMOS Basic provides you with dozens of useful keyboard commands. These
can be used in anything from an Arcade game to an Adventure. It's even
possible to write a fully fledged wordprocessor entirely in AMOS Basic!



                 =INKEY$ (function to get a keypress)

k$=INKEY$

This function checks whether the user has pressed a key, and returns
its value in the string k$

  Note the INKEY$ command doesn't wait your input in any way. If the
user hasn't entered a character, INKEY$ will simply return an empty
string "".

  INKEY$ is only capable of reading keys which return a specific Ascii
character from the keyboard. Ascii is a standard code used to represent
all the characters which can be printed on the screen.

  It's important to realise that some keys, like HELP button or the
function keys, use a rather different format. If INKEY$ detects such a
key, it will return a character with a value of zero (CHR$(0)). You can
now find the internal scan code of this key using a separate SCAN CODE
function.



               =SCANCODE (input the scancode of the last
                        key input with INKEY$)

s=SCANCODE

SCANCODE returns the internal scancode of a key which has previously
entered using the INKEY$ function. This allows you to check for keys
which do not produce a character from the keyboard, such as HELP or
TAB. Type the following small example:

      Do
        While K$=""
          K$=Inkey$
        Wend
        If Asc(K$)=0 Then Print "You pressed a key with no ASCII Code"
        Print "The Scancode Is";Scancode
        K$=""
      Loop


                =KEY STATE (test whether an individual                     250
                         key has been pressed)

t=KEY STATE(s)

Check if a specific button has been pressed on the Amiga's keyboard. s
is the internal scancode of the key you want to check. If this key is
currently being depressed then KEY state will return a value of true
(-1), otherwise the result will be false (0).



                   =KEY SHIFT (return the status of
                            the shift keys)

keys=KEY SHIFT

KEY SHIFT returns the current status of the various control keys. These
keys such as SHIFT or Alt cannot be detected using the standard INKY$
or SCANCODE system. But you can easily test for any combination of
control keys with just a single call to the KEY SHIFT function. "keys"
is a bit map in the following format:

        Bit  Key Tested         Notes
        ---  ----------         -----
         0   Left SHIFT
         1   Right SHIFT
         2   Caps Lock          Either ON or OFF
         3   CTRL
         4   Left ALT
         5   Right ALT
         6   Left AMIGA         C= key on some keyboards
         7   Right AMIGA

If a bit is set to a one, then the associated button has been held down
by the user.



                    INPUT$(n) (function to input n
                       characters into a string)

INPUT$ enters n characters straight from the keyboard, waiting for each
one in turn. As with INKEY$, these characters are not echoed onto the
screen.

  x$ is a string variable which will be loaded with your new
characters. n holds the number of characters to be entered. Example:

        Clear Key : Print "Type In Then Characters"
        C$=INPUT$(10) : Print "You entered ";C$

This insturction *not* the same as the standard INPUT command. The two
instuctions are completely different. Also note that there's a special
version of INPUT$ which can be used to read your characters from the
disc.



                     WAIT KEY(wait for a keypress)                         251

WAIT KEY

Waits for a single keypress.



                  KEY SPEED (change key repeat speed)

KEY SPEED lag,speed

KEY SPEED lets you tailor the speed of the keyboard to your own
particular taste. The new speed will be used for every part of the AMOS
system, including the editor.

  "lag" is the time in 50th of a second between pressing a key, and the
start of the repeat sequence.

  "speed" is the delay of second between each successive character.



                CLEAR KEY (initialise keyboard buffer)

CLEAR KEY

Whwnever you enter a character from the keyboard, its Ascii code is
placed in an area of memory known as the keyboard buffer. It is this
buffer that is sampled by the INKEY$ function to get your key presses.

  CLEAR key erases this buffer completely, and returns your keyboard to
this original state. It's especially helpful at the start of a program,
as the buffer may well be full of unwanted information. You can also
call it immediately before a WAIT KEY comand to ensure that the program
waits for a fresh keypress before preceding.



            PUT KEY (Put a string into the keyboard buffer)                252

PUT KEY a$

Loads a string a characters directly into the keyboard buffer. Carriage
returns can be included using a CHR$(13) character.

  The most common use of PUT KEY is to set up defaults for your input
routines. Here's a demonstration:

        Do
          Put Key "No"
          Input "Another Game";A$
          If A$="No" Then Exit
        Loop



Input/Output
============

                 INPUT (load a value from the user and
                          put it a variable)

INPUT

Provides you with a standard way of entering information into one or
more variables. There are two possible formats for this instrucion:

INPUT vars[;]

Enters a list of variables directly from the keyboard. "var" can
contain any set of variables you like, separated by commas. A question
mark will be automatically displayed at the current cursor position.

INPUT "Prompt";variable list[;]

Prints out the "prompt" string before entering your information. Note
that you must always place a semi-colon between your text and the
variable list. You are *not* allowed to use a comma for this purpose.

  The optional semi-colon ";" at the end of your variable list
specifies that the text cursor will not be affected by the INPUT
instruction, and will retain its original position after the data has
been entered.

  When you execute one of these commands, Basic will wait for you enter
the required information from the keyboard. Each variable in your list
must be matched by a single value from the user. These values must be
of the same as your original values, and should be separated by commas.



                      LINE INPUT (input a list of                          253
                   variables separated by a Return)

LINE INPUT "Prompt";variable list[;]

Line input is exactly same as INPUT, except that it uses a Return
instead of a comma to separate each value you enter from the keyboard.






                          19: OTHER COMMANDS                               254
                     ----------------------------


                               PRINT / ?
               (print a list of variables to the screen)

PRINT items

The PRINT instruction displays some information on the screen, starting
from the current cursor position.

  Each element in your list must be separated by either semi-colon or a
comma. A semi-colon prints the data immediately after the previous
value, whereas a comma first moves the cursor to the next TAB position
on the screen.

  Normally the cursor will be advanced downwards by a single line after
each PRINT instruction. This can be suppressed by adding a separator
after the print.

        PRINT 10,20*10,"Hel";
        PRINT "lo"



                       USING (formatted output)

PRINT USING format$;variable list

The USING statement is used in conjunction with PRINT to provied fine
control over the format of your printed output.

  format$ specifies a list of characters which defines the way your
variables will be displayed on the screen. Any normal text in this
string will be printed directly, but if you include one of the
characters ~#+-.;^ then one of a range of useful formatting operations
will be performed.

 ~  Formats a sting variable. Every ~ is replaced by a single character
    from your output string, taken from left to right.

        PRINT USING "This is a ~~~~~ demonstration of USING";"Small"

 #  Each hash character specifies a single digit to be printed out from
    your cariable. Any unused digits in this list will be automatically    255
    replaced by spaces.

 +  Adds a plus sign to a number if its positive, and a minus minus
    sign if it's negative.

        PRINT USING "+##";10 : PRINT USING "+##";-10

 -  Only includes a sign if the number is negative. Positive numbers
    are preceded by a space.

 .  Places a decimal point in the number, and centres it neatly on the
    screen.

 ;  Centres a number but doesn't output a decimal point.

 ^  Prints out a number in exponential form.

        PRINT USING "Here is a number ^";12345.678



                           REM / ' (comment)

REM comment

The REM statements is used to add comments to your Basic program. Any
text typed in after a REM statement will be completely ignored by AMOS
Basic.

        REM This is a comment
        ' this is a comment.

So, a quote mark "'" can also be used, but it *must* be placed at the
absolute beginning of the line.



                   DATA (place a list of data items                        256
                       in a AMOS Basic program)

The DATA statement allows you to incorporate whole lists of useful
information directly inside a Basic program. This data can be
subsequently loaded into one or more variables using the READ
instruction. Each variable in your list is separated by a single comma.

        DATA 1,2,3,"Hello"

Unlike most other Basics, the AMOS version of this instruction also
lets you include expression s as part of your data. So the following
lines of code are equally acceptable:

        DATA $FF50,$890
        DATA %111111111111,%1101010101
        DATA A
        Label: Data A+3/2.0-Sin(B)
        Data "Hello"+"There"

It's important to realise that the "A" at LABEL will be input as the
contents of variable A, and not the character A. The expression will be
evaluated automatically during the READ operation using the lastest
values of A and B.

  Also note that each DATA instruction must be the only statement on
the current line. Anything after this command will be totally ignored!
Data statements can be placed anywhere in your Basic program. However,
any data you store inside an AMOS procedure will not be accessible from
the main program.



                      READ (read some data a DATA
                      statement into a variable)

READ list of variables

Loads some informatoin stored in a DATA statement into a list of
variables. READ uses a special marker to determine the location of the
next piece of data to be entered. At the start of your program, the
marker is moved to the first item of the first DATA statement. Once
this item has been read, the marker is advanced so that it points to
the next item in your list. As you might expect, the variables you read
must be exactly the same type as the data held at the current position.
Example:

        T=10
        Read A$,B,C,D$
        Print A$,B,C,D$
        Data "String",2,T*20+rnd(100),"AMOS "+"Basic"



                RESTORE (set the current READ pointer)                     257

RESTORE Label
RESTORE LABEL$
RESTORE Line           RESTORE changes the point at which a subsequent
RESTORE number         READ operation will expect to find the next DATA
                       statement. Each AMOS procedure has its own
individual data pointer. So any calls to this command wlil only apply
to the *current* procedure!

  "label" is a label which specifies the position of the first DATA
statement to be read. This label name can be calculated as part of an
expression. The following Basic commands are perfectly legal:

        RESTORE L
        RESTORE "L"+"A"+"B"+"E"+"L"

Similarly, line selects the line number of the next DATA statement.
Like "label" it can be entered as an expression:

        RESTORE TEST+2

By allowing you to jump at will through the DATA statements in your
program, RESTORE lets you choose your information depending on the
actions of the user. Each room of an adventure, for instance, could
have its description stored in a list of simple DATA statements. To
read this description you could use something like:

        Restore ROOM*5+1000 : Rem Each ROOM has 5 data statements
        Read DESC$ : Print DESC$
            :            :

Obviously, if a data statement does not exist at the line specified by
RESTORE, and appropriate error message will be generated. Beware of
trying to use this command inside a procedure. In order to work, your
DATA statements *MUST* be within the current procedure.



                   WAIT (wait in 50ths of a second)                        258

WAIT n

Suspends an AMOS Basic program for n/50 of a second. Any functions
which use interrupts, such as MOVE and MUSIC, will continue to work as
normal during this period.



                 =TIMER= (count in 50ths of a second)

v=TIMER
TIMER=v

TIMER is a reserved variable which is incremented by 1 every 50th of a
second. It's commonly used to set the seed of the random number
generator like so:

        Randomize Timer



                      NOT (logical NOT operation)

v=NOT(d)

This function changes every binary digit in a number from a 1 to a 0
and vice versa. Since True=-1 (%1111111111111) in binary and False=0,
NOT(True)=False. Example:

        Print Bin$(Not(%1010),4)
( result: 0101 )
        If Not(True)=False Then Print "False"



                          TRUE (logical TRUE)

v=TRUE

Whenever a test is made such as X>10, a value is produced. If the
condition is true then this number is set to -1, otherwise it will be
zero.

        If -1 Then Print "Minus 1 Is TRUE"
        If TURE Then Print "and TRUE Is ";TRUE


                         FALSE (logical FALSE)

v=FALSE

Returns a value of zero. This is used by all the conditional operations
such as IF...THEN and REPEAT...UNTIL to represent FALSE.

        Print FALSE
( result : 0 )

20: DISc ACCESS

The AMOS disc commands give you total access to the Amiga's filing
system. These can be exploited to create anything from a simple reader
to a fully fledged database.

Drives and volumes

As you know, the Amiga lets you label your discs in a number of
different ways. If you're unfamiliar with the CLI, you may find some of
these terms a little confusing. So I'll now provide you with a brief
explanation of the varoius naming conventions:


Drives
------
Floppy Drives: Are assigned names in the following format

        DFn:

n is a single digit which holds the number of your drive. The first
floppy drive in your system (usually the internal drive) is known as
DF0: then comes drives DF1:, DF2: and DF3: if they're installed.

Hard drives: These are specified using:

        DHn:

Where n is the number of your hard drive (or a partition on it).


Volumes
-------
The Amiga also creates a separate VOLUME name for each individual disc.
Tihs label can be substituted for the drive name in any of your AMOS
Basic commands. AMOS will automatically check each available drive for
the required disc. If it can't be found, you'll get a "drive not
mounted" error.

  Whenever you prepare a new disc from the Workbench, the disc will be
assigned the name "Empty". To change this label from the WB, simply        261
click on the RENAME option and enter your new name in the dialogue box
provided. This name can be practically any string of characters you
like, but it must be terminated with a colon character when it's used
in your programs, just like the drive name. Here are some typical
volume names for you to examine:

        AMOS:
        AMOS_DATA:

WARNING! If you create several discs with the same name or swarp them
around indiscriminately, the Amiga can easily get confudsed as to which
disc you are actually referring to. In these circumstances, you'll need
to enter the drive name instead. This will tell AMOS precisely where
the required disc can be found on your system.

  You are strongly recommended to assign a different name to each and
every disc you use. This takes no more than a couple of secs from the
WB but it does simplify things enormously.


Logical devices
---------------
Finally, there's also a set of objects known as logical devices. These
are used by the Amiga's operating routines to determine the precise
position of important systems files such has device handlers or fonts.
Each device is normally assigned to a specific directory on the current
start-up disc. Here are some examples used by AMOS.

        FONTS:  A directory containing the current fonts.
        LIBS:   Holds a library files required byt the AMOS SAY command.


Cross Dos
---------
If you've bought the separate CROSS DOS package and installed it into
memory, you'll also be able to access IBM or ST format discs within
AMOS Basic. These discs are assigned names starting with letters DI.

        DIn:    (where n is the number of your drive)

In order to convert your STOS programs to AMOS Basic, you'll need to
save them in ASCII format using the FSAVE "*.ASC" option from STOS.
Then insert the disc into an Amiga floppy drive that has been mounted
by Cross-Dos as an IBM drive.

  Due to the differences between AMOS and STOS, many STOS progs will
require modifying slightly before they will run under AMOS.


Directory changing                                                         262
==================


           DIR (print out the directory of the current disc)

DIR [PATH$] [/W]

Lists all the files on the current disc. If the optional path$ is
specified, only the files which satisfy a certain set of conditions
will be displayed. Any folders in the listing will be distinguished by
a leading "*" character.

  The listing can be halted at any time by pressing the spacebar. To
resume, simply press the spacebar once again.

  Note that if you change discs and try to get a directory listing, you
may be presented with a "device not mounted" error. This is because
you've removed the current disc without informing AMOS Basic. The
solution is to simply update the current directory name to the new
using a line like: DIR$="DF0:" before calling DIR

  /W lists the files in two columns across the screen. This effectively
doubles the number of files which can be displayed at any one time. The
path string consists of three main elements:

        [Disc:][Directory/] Filter.

Filter defines a set of conditions which should be satisfied for each
file in your listing.

   Normal Text: Each character in your text should match exactly one
                character in the filename to be displayed. Example:

        Dir "Music"
( result : Music )

   * (asterix): Match any list of letters in your filenames up to the      263
                next control character.


        Dir "M*"

As a default, this option will ignore any files which include an MS-DOS
type extension. So a file lake: Mad.Asc  on the disc would not be
listed.

   . (period): Matches the extension of a filename. It's commonly used
               in conjunction with the "*" command to list all files
               with a particular extension.

   ? (question mark): Matchces a single character at the current
                      position.



                   =DIR$= (change current directory)

s$=DIR$
DIR$=s$

DIR$ contains the directory which will be used as the starting point
for all future disc operations, such as loading and saving. It's very
similar to the CD command from the CLI, with the added advantage of
allowing you to read the directory as well as just change it. Examples
of the usage:

        Print Dir$
        Dir$="AMOS:Iff/"



            PARENT (sets the current path up one directory)                264

PARENT

The action of PARENT is to load the current directory with the parent
of the present folder. By repeatedly using this command, you can
quickly get back to your original root directory.



                    SET DIR (set style used by DIR)

SET DIR n[,filter$]

Sets the style of your directory listings. n is the number of
characters ranging from 1-100 which will be displayed in each filename.
Note that this setting has NO effect on the actual length of your
names. It only changes the way they will be listed on the screen.

  "filter" is a list of pathnames which are to be EXCLUDED from your
directory searches. All filenames that match this filter are completely
ignored and will not be displayed as part of your directory. This can
be used to supress the annoying ".INFO" files which cointain the icon
definitions used by the WB. Note that it's possible to ignore a whole
list of filepaths at once. Simply terminate each name with a single "/"
character. As a default, the filter is set to:

        ".INFO/*.INFO/*.*.INFO"



Common disc operations                                                     265
======================


                        DFREE (disc free space)

f=DFREE

Returns the amount of free space remaining in bytes on the current disc.



                        MKDIR (create a folder)

MKDIR f$

Creates a new folder on the disc with the name f$. Example:

        MkDir " Df0:TEST"



                   KILL (erase a file from the disc)

KILL f$

Deletes the file f$ from the current disc.



                        RENAME (rename a file)

RENAME old$ TO new$

Changs the name of a file.


Selecting a file                                                           266
================


                        =FSEL$ (select a file)

f$=FSEL$(path$[,default$][,title1$,title2$])

This function lets you choose your files directly from the disc, using
the standard AMOS file selector.

  "path$" sets a search pattern which determines which files will be
displayed in your listing.

  After you've selected a file, FSEL$ will reuturn either its full
pathname, or an empty string "" if you selected QUIT.

  "default$" chooses a filename to be used as a default.

  "title1$" and "title2$" are optional text strings which describe a
title to be displayed at the top of your file selector. Example:

        F$=Fsel$("*.IFF","","Load an IFF File")
        If F$="" Then Edit : Rem Return to editor if no file was chosen.
        Load IFF F$,0


Running an AMOS program from disc
=================================


                  RUN (execute an AMOS Basic program)

RUN [file$]

Although it's easy enough to execute your progs straight from the
editor, we've also included a separate RUN command. This version of the
command without file$ can only be used from direct mode.

  But the RUN file$ statement may also be placed inside a Basic
program. This allows you to chain a list of programs together. Note
that when you run a program in this way, the existing program will be
removed from memory and any variables will be lost. Any data screens
that have been created though, will remain intact, thus allowing
intermediate loading screens to be displayed.

  This command is fantastically useful, as it allows you to split any
AMOS game into a number of levels which can be loaded separately from
the disc. Each level can now be writeen as a completely independent
program. So the only limit to the size of your games is the amount of
storage space on the disc! You can therefore produce some massive games
with this system!

See also PRUN


Checking for the existence of a file                                       267
====================================


                =EXIST (check if specified file exists)

flag=EXIST(f$)

EXIST checks the current directory for the file f$. If it's found, then
a value -1 will be returned, otherwise 0. This EXIST function is
capable of checking for the existence of anything from a single file to
an entire disc. Example:

        Print Exist("DF1:"): Rem Has a second drive been connected?



             =DIR FIRST$ (get first file in the directory
                         satisfying path name)

file$=DIR FIRST$(path$)

Returns a string containing the name and length of the first file on
the disc which satisfies the current search path$. WHen this function
is called, the entire directory listing will be loaded into memory. You
can now retrieve the name of the next file in the directory using a
call to the DIR NEXT$ function.

        Print Dir First$("*.*")



        =DIR NEXT$ (get the next file satisfying current path)

file$=DIR NEXT$

Returns the next filename in the directory listing created by a
previous DIR FIRST$ command. After the last item has been read from
this list, a string will be returned containing the empty string "".
The entire directory array will now be erased and the memory it
consumes will be released for the rest of your Basic program. Here's an
example which prints out all the files in the current directory:

        F$=Dir First$("*.*")
        While F$<>""
          Print F$ : Bell : Wait 30
          F$=Dir Next$
        Wend

See EXAMPLE 20.1 in the manual folder.


Disc files                                                                 268
==========
Files are just collections of information which have been grouped
together in one place on the disc. Each file is assigned its own name
which may contain anything from 1 to 255 characters.

  Before you can use one of these files, you first need to initialize
it using either the OPEN IN, OPEN OUT, or APPEND instructions. When you
open a file, you assign it to a "channel" number ranging from one to
ten. This number will be used in all future disc operations to identify
the file you are currently working with. The commodore Amiga supports
two types of disc files: Sequential files and Random access files.


Sequential files
================
Sequential files are the standard files which are used on the Amiga.
The reason for their name is that they only allow you to read your
information in the precise sequence it was originally created. This
means that if you wanted to change just one piece of the data in the
middle of a sequential file, you would have to read in the whole file
up and including this value, and then write the entire file back to the
disc.

  AMOS Basic allows you to access sequential files for either writing
or reading, but never for both at the same time.

        Open Out1,"file.seq"
        Input "What is your name";N$
        Print #1,N$
        Close 1

This creates a file called FILE.SEQ containing your name. In order to
read this information back from the file, type in the lines.

        Open In 1,"file.seq"
        Input #1,N$
        Print "I remember your name. It's ";N$
        Close 1

Notice how both these programs perform three separate operations:

 * Open the file using OPEN IN, OPEN OUT or APPEND
 * Access the file with INPUT# or PRINT#.
 * Close the file with CLOSE. Note that if you forget to do this, any
   changes to the file will be lost!

These three steps need to be completed in exactly this order, every
time you access a sequential file.



                   OPEN OUT (open a file for output)                       269

OPEN OUT channel,n$

Opens a sequential file for writing. If this file already exists it
will be erased. "channel" is a number between 1 and 10 and is used to
identify your new file in your subsequent PRINT# commands. n$ is the
name of the file to be opened.



                  APPEND (add some information to the
                         of an existing file)

APPEND channel,name$

Opens a sequential file for output. If this file exists, the new data
is added onto the end. This allows you to expand your files at any time
once they've been defined.



                    OPEN IN (open a file for input)

OPEN IN channel,f$

Sets up a file for reading. If this file doesn't exist, it will be
automatically created. "channel" is a number ranging from 1 to 10 which
is used by various INPUT instructions to refer to your open file.



                         CLOSE (close a file)

CLOSE n

Closes file number n. WARNING! If you forget to close a file after you
have finished with it, any changes you've made will be ignored!!



                  PRINT # (print a list of variables
                         to a file or device)

PRINT #channel,variable list

This command is identical to the normal print instruction, but instead
of displaying the information to the screen, it outputs it to a file or
output device specified by the channel number. Here's an example:

        Open Out 1,"TestFile"
        Print #,"Hello"
        Close 1

As with PRINT you can abbreviate PRINT # to ? #.



                  INPUT # (input a list of variables
                        from a file or device)

Reads information from either a sequential file or a device such as the    270
serial port. Like the standard INPUT command, it enters a list of
values and loads them into a set of Basic variables. As always, each
value in the list must be separated by a comma. Additionally, every
line of data also needs to be terminated by its own <line feed>
character. This is equivalent to the Return you pressed when you
entered a line from the keyboard.



                LINE INPUT # (input a list of variables
                        not separated by a ",")

LINE INPUT #channel,variable list
LINE INPUT #channel,separators,variable list

This function is identical to INPUT #, except that it allows you to
separate your list of data using any character you with instead of the
standard comma. If the separator is omitted, it's automatically set to
the <return> character. When you're reading text, LINE INPUT # is
always the preferred choice. That's because the commas found in normal
English will be treated as a separator by the INPUT # command. This
will confuse your program completely.



                SET INPUT (set End Of Line characters)

SET INPUT c1,c2

Sets the End-Of-Line chars which will be used to terminate a line of
data. The Amiga expects a single <line feed> at the end of each line,
whereas most other computers (including the ST) require both a Return
and <line feed>. SO if you try importing your ST files via the serial
cable, you'll end up with dozens of spurious Return characters in your
files. Fortunately you can  sidestep this problem using SET INPUT.

  c1 and c2 hold a pair of ASCII values which will be used for your
separators. If you want to use a single character ,simply load c2 with
a negative value such as minus one. Here's a couple of exmples:

        Set Input 10,-1 : Rem Standard Amiga Format
        Set Input 13,10 : Rem ST Format



           =INPUT$ (inputs a number of chars from a device)                271

X$=INPUT$ (f,count)

Reads "count" characters from device or file number f.



                      =EOF (test for end of file)

flag=EOF (channel)

EOF is a useful function which tests to see if the end of a file has
been reached at the current reading position. If it has, EOF returns a
result of -1, otherwise 0.



                       LOF (length of open file)

length=LOF(channel)

Returns the length of an open file. It makes no sense to use this
function in conjunction with devices other than the disc.



                     POF (variable holding current
                       position of file pointer)

pos=POF(channel)

The POF function changes the current reading or writing position of an
open file, for example:

        Pof(1)=1000

This sets the read/write position to 1'000 characters past the start of
the file. Oddly enough POF can be used in this way to provide a crude
form of random access when using sequential files! The reason this
works is simply that disc drives are inherently random and all
sequential operations are effectively simulated using random access.



Random access files
===================
Random access files are so called because you can access the
information stored on the disc in any random order you like. In order
to use these files you first need to understand a little bit of theory.

  All random access files are composed of units called records, each
with their own unique number. These records are in turn split up into a
number of separate fields. Every field contains one individual piece of
information. When you use sequential files, these fields can be any
length you with, as the file will only be read in one direction. Random
access files, however, always require you to specify the maximum size
of these fields in advance.

  Supposing you wanted to produce a file containing a list of names and
telephone numbers. In this case you could use the fields:

        Field           Max length                                         272
        -----           ----------
        SURNAME$             15
        NAME$                15
        CODE$                10
        TEL$                 10

You could now define these fields using a line like:

        Field #1,15 as SURNAME$,15 as NAME$,10 as CODE$,10 as TEL$

It's important to realize that the strings specified by the FIELD
instruction can also be used as normal string variables. This allows
you to read and write information to any particular field. For example:

        SURNAME$="HILL"
        TEST$=SURNAME$ : Print TEST$

After you've loaded your record with information, you can write it onto
the disc using PUT command. Example:

        Put 1,10

Loads data into record 10 of the file opened on channel 1

  Similarly, you can read a record using the GET instruction:

        Get 1,10



             OPEN RANDOM (open a channel to a random file)

OPEN RANDOM channel,n$

Opens a random access file called n$ on the current disc. When you're
using this instruction, you should always define the record sturcture
immediately afterwards using the FIELD$ command.



                    FIELD (define record structure)

FIELD channel,length1 AS field1$,length2 AS field2$......

FIELD allows you to define a record which will be used for a random
access file. This record can be up to 65535 bytes in length.

        Field 1,15 as SURNAME$,15 as NAME$,10 as CODE$,10 as TEL$



              PUT (output a record to random access file)                  273

PUT channel,r

PUT moves a record from memory into record number r of a random access
file. Before use, the contents of the new record should first be placed
in the field strings defined by FIELD, using a statement such as:

        SURNAME$="HILL"

Although you can write existing records in any order you like, you're
not allowed to scatter records on the disc totally at random. This
means that if you have just created a file you can't type in something
like:

        Put 1,1
        Put 1,5

In this case, the PUT 1,5 instruction will generate an error, as there
are no records in the file with numbers between 2 and 5. Record 2 must
be the next new record in the file, then 3,4... example:

        Open Random 1,"TELEPHONE"
        Field 1,30 As NAME$, 30 As Tel$
        INDEX=1
        Do
          Input "Enter a name";NAME$
          Exit If NAME$=""
          Input "Enter telephone number";TEL$
          Put 1,Index : Inc INDEX
        Loop
        Close 1



            GET (input a record from a random access file)

GET channel,r

Reads record number r stored in a random access file opened using OPEN.
It then loads this record into the field strings created by FIELD. The
strings can now be manipulated in the normal way. Note that you can
only use GET to retrieve records which are actually on the disc. If you
try to grab a record number which does not exist then an error will be
generated. Example:

        Open Random 1,"TELEPHONE"
        Field 1,30 As NAME$, 30 As TEL$
        Do
          Input "Enter Record number";INDEX
          Exit If Index=0
          Get 1,INDEX : Print NAME$ : Print TEL$
        Loop
        Close 1


The Printer                                                                274
===========


                    LLIST (print a part or all of a
                         program on a printer)

LLIST

Lists the entire program straight to the printer. Try listing some of
the Basic programs supplied on the DATA disc. These provide a perfect
demonstration of the various programming tehcniques neeked to write
your own AMOS Basic games. Feel free to modify them as much as you
like.



                       LPRINT (output a list of
                       variables to the printer)

LPRINT variable list

This is exactly the same as PRINT but sends your data to the printer
instead of the screen. Example:

        Lprint "Hello"

See PRINT, USING, PRINT #



                LDIR (list a directory to the printer)

LDIR [PATH$] [W/]

Lists the directory of the current disc to the printer. See DIR for
more details.


External devices
================


               OPEN PORT (open a channel to an I/O port)

OPEN PORT channel,"PAR:"  (open a channel to the Paraller interface)
OPEN PORT channel,"SER:"  (open a channel to the RS232 port)
OPEN PORT channel,"PRT:"  (open a channel for the printer)

OPEN PORT allows you to communicate with external devices such as the
RS232 port. All the standard file commands can be performed as normal,
except for commands like LOF or POF which are obviously only relevant
to disc operations. Example:

        Open Port 1,"SER:"                                                 275
        For X=0 To 10
          Print #1,"AMOS BASIC"
        Next X
        Close 1

This program prints out ten lines of text on the device connected to
the RS232 port. If your printer uses the paraller port change line 10
to:

        Open Port 1,"PRT:"

Similarly you can input information from a device such as a modem with
a line like:

        Input #1,A$ : Print A$

When accessing these external devices all the normal input statements
are available for your use, including INPUT$ and LINE INPUT.



            =PORT (function to test if channel is waiting)

n=PORT(channel)

Tests to see if an input device is ready to send you some information.
If the device is waiting for you to read it, a value of -1 will be
returned by this function, otherwise 0 (false).








                         21: SCREEN COMPACTION                             276
                      ---------------------------


                       SPACK (screen compaction)

SPACK s TO n [tx,ty,bx,by]

The SPACK command packs screen s into memory bank n. Everything about
the current image is saved, including its mode, screen size, offset and
display position. This allows you to recreate your screen in exactly
its original state.

  s is the number of the screen which contains yur image. n holds the
number of a memory bank from 1-16. If this bank doesn't currently
exist, it will be reserved for you automatically. Your new bank will be
stored in FAST memory if it's available, and will be saved along with
our Basic program. After you've called this function, the size of your
screen can be found using LENGTH. Example:

        F$=FSEL$("*","","Load a picture")
        Load Iff F$,0
        Spack 0 To 1
        Print "The length of your new bank is ";Length(1);" Bytes"
        Wait Key
        Screen Close 0
        UnPack 1 To 0 : Rem recreate compacted screen

You don't, of course have to compact an entire screen with this
instruction. The optional parameters let you compress any rectangular
section of the display you like.

  tx,ty now hold the coordinates of the top left corner of this region.
bx,by set the position of the bottom right corner. All x coordinates
are rounded to the nearest 8 pixel boundary.

  Note that in order to achieve the maximum memory reduction, SPACK
will attempt to compact your image using several different strategies.
It will then compress your image using the method which consumes the
least amount of memory. One side effect of this efficiency, is that it
usually takes around 6 secs to compress one of your images. This is        277
hardly a disadvantage however, as normally the compaction is only
required when you are writing your programs.

  Since each image can be unpacked on the screen in less than a second,
there's no risk of interference with the speed of your games. It speeds
is of the essence though, you may wish to use the CBLOCK system
instead. See the section on Background Graphics for more details.

  Incidentally, if you compare the compacted size of your files with
their original length on the disc, you may be mislead into
underestimating the size of the memory reduction. It's important to
realize that the vast majority of these files have ALREADY BEEN
COMPESSED using the standard IFF compaction routines. So it's rather
surprising that AMOS can reduce them by a further 20 % !

  Compacted screens are perfect for the titles and hi-score tables
required in an arcade game, as they allow you to introduce snazzy
screen effects without consuming enormous quantities of memory. They
can also be incorporated directly into RPGs and Adventures.



                         PACK (pack a screen)

PACK s TO n [tx,ty,bx,by]

Compresses screen s into bank number n. Unlike the previous SPACK
command, only the image data is compressed. So your compacted screen
must always be unpacked directly into an existing screen.

  Because of the way images are decompressed, there will be a
noticeable shimmer effect unless you've previously double buffered your
screens. Try to avoid using PACK with single buffered screens. It's
much more sensible to call the SPACK system for this purpose.

  If the optional coordinates are included, only a section of the image
will be compressed.

  Since PACK is fully compatible with the standard AUTOBACK system,
it's easy to combine compacted images with moving screens. If you are
using Autoback 2  mode, you'll even be able to unpack your images
BEHIND existing bobs. It's therefore possible to exploit this
instruction in conjunction with SCREEN OFFSET to create fantastic
scrolling backgrounds for your games.



                  UNPACK (unpack a compacted screen)

Decompresses a screen which has been previously compacted using the
SPACK or PACK instructions. Each compaction routine has its own
specifix form of the UNPACK command.

 SPACK
 -----

UNPACK b TO s

Opens a screen s and restores the compacted screen into bank b. If this
screen already exists, it will completely replaced by the new image.
Once the screen has been unpacked, it will be neatly flicked into view.    278

 PACK
 ----

PACKed screens can be unpacked using two separate instructions. These
take an image from a memory bank, and load it straight into an existing
screen. WARNING! The destination screen MUST be in exactly the same
format as your compacted picture, otherwise you'll get an
"illegal function call" error.

  When you unpack your screens, you may notice that the effect is
slightly messy. That's 'cause the PACK command is only really intended
for use with the double buffering system. Providing your screen is
double buffered, you'll get a delightfully smooth result.

UNPACK b

Unpacks the screen at its original position

UNPACK b,x,y

Redraws your image starting at coordinates x,y. If the new image
doesnt' fit into the current screen, you'll get an error message.









                           22: MACHINE CODE                                279
                      ---------------------------

Number conversion
-----------------

                     =HEX$ (convert number to hexadecimal)

h$=HEX$(v)
h$=HEX$(v,n)

HEX$ converts the integer v into hexadecimal notation (base 16). It
returns a sequence of n hexadecimal characters in the string h$. Example:

        Print Hex$(Colour(1),3)



                    =BIN$ (convert number to binary string)

b$=BIN$(v)
b$=BIN$(v,n)

Converts a number into binary notation (base 2).


Memory manipulation
-------------------


                            =PEEK (get byte address)

v=PEEK(address)

Returns the 8-bit byte stored at "address"



                         POKE (change byte at address)                     280

POKE address,v

Copies the number v into "address". v must always lie in the range 0-255.
Be warned: POKE can be very dangeroud. If you poke around
indiscriminately, you will almost certainly crash the Amiga!



                          =DEEK (get word at address)

v=DEEK(address)

Reads the two-byte word found at "address". "address" MUST be even or
an address error will occur.



                         DOKE (change word at address)

DOKE address,value

DOKE loads a two-byte number between 0 and 65535 into the memory location
at "address". In knowledgeable hands this function caan be very useful.
Since even the best of us make mistakes however, you should always save
a copy ot your progs to the disc before attempting to use this function
in a new routine. Example:

        Doke Phybase(1)+1000,65535



                      =LEEK (read a long word at address)

v=LEEK(address)

Returns the four-byte long word stored at "address". Like DEEK, the
address used with this function must always be EVEN. If bit 31 of
the return value is set to 1, v will be diplsyed as a negative
number. This isn't a bug. It's just a side effect of the way AMOS
deals with numbers.



                       LOKE (change long word at address)                  281


LOKE address,n

LOKE copies the four-byte number into "address". Example:

        Loke Phybase(1)+10000,$FFFFFFFF

Indiscriminate use of this function can lead to the Amiga crashing
horribly, so take care.



                      =VARPTR (get address of a variable)

address=VARPTR(variable)

Returns the address in memory of a Basic variable. Each type of variable
is stored using its own individual format:

Integers: VARPTR finds the address of the four bytes containing the
contents of your variable.

Floating points: VARPTR returns the location of four bytes which hold
the value of the variable in the IEEE single precision format

Strings: The VARPRT address points to the first character of the string.
Since AMOS Basic doesn't end its strings with a CHR$(0), you must
obtain the length of the string using something like:

DEEK(VARPTR(A$)-2), where A$ is the name of your variable. You could
also use LEN(A$) of couse.



                           COPY (copy a memory block)

COPY start,finish TO destination

This command is used to rapidly move large sections of the Amiga's
memory from one place to another. "start" and "finish" are the
addresses of the first and last bytes of your data respectively.

  "destination" points to a memory area which will be loaded with
your new data. All these addresses MUST be even, or you'll get an
address error.



                    FILL (fill memory block with a longword)               282

FILL start TO finish, pattern

Fills a selected region of memory with the four bytes held in
"pattern". "start" and "finish" determine the position and size of
the block which is to be filled. These addresses MUST BE EVEN!

  "pattern" is a long word containg a four byte fill pettern. This
will be copied into each group of memory locations between
"start" and "finish".



                        =HUNT (find a string in memory)

f=HUNT(start TO finish, s$)

Searches through the Amiga's memory for the sequence of characters held
in s$. "start" is the address of the first byte in memory to be searched,
and "finish" is the address of the last. On completion, f will hold
either 0 (in the string in a$ was not found) or the location of f$.



Bitwise operations
------------------


                               ROL (rotate left)

ROL.B n,v
ROL.W n,v
ROL.L n,v

ROL is a Basic version of the ROL instruction found in 68000 assembly
language. The effect is to take the binary representation of a number
in v, and rotate it left by exactly n places.

  If v is a single variable, then the number to be rotated is taken
directly from v. But if v is an expression, then it's treated as the
address of your number instead. Example:

        A=8
        Ror 1,A
        Print A
( result: 4 )

ROR is capable of dividing any positive value by a power of two. The
resulting calculation will be performed much faster than the equivalent
"/" operation.




                               ROR (rotate right)                          283

This is very similar to ROL but rotates the number in the opposite
direction.



                               =BTST (test a bit)                          284

Tests the binary digit at position n in the variable v. If v is an
expression, it will be used as the address of the bit which is to
be checked. In this case n will be automatically ANDed with 7
before proceeding.

  After BTST has been called, b will be loaded with -1 if the bit
at position n is set to 1, otherwise it will be 0.



                             BSET (set a bit to 1)

BSET n,v

Sets the bit at position n to 1 in the variable v.



                              BCHG (change a bit)

BCHG n,v

Changes bit number n in the variable v. If this bit is currently 1
then the new value will be a zero, and vice versa.



                               BCLR (clear a bit)                          285

BCLR n,v

Clears bit number n in variable v by setting it to zero. Like all
the bitwise operations, if v is an expression, then it will be used
as the location of your data in memory.



Using assembly language
-----------------------
AMOS Basic includes special facilities which allow you to combine
assembly language routines with your Basic programs. It's worth
emphasising that, because of the sheer power of the AMOS system,
machine code is only rarely useful. We've added these features solely
for existing assembly language programmers who may wish to optimize
their Basic programs with the occasional bit of machine code.



                   PLOAD (reserve a memory bank for
                          some machine code)

PLOAD "filename",bank

Reserves a memory bank and loads it with a machine-code program from
the disc. "bank" is the number of a memory bank which is to be reserved
for your program. If it's negative, then the bank will be calculated
using the absolute value of this number, and the required memory area
will be allocated from CHIP mem.

  Once you've loaded a program in this way, you can save it on the disc
as an normal ".ABK" file. Since the banks created by this function are
permanent, it will also be saved directly with your AMOS programs.

  Your program must consist of a machine code file in the standard
Amiga format. In practice, it can contain practically anything you
like, with the following restrictions:

 * The code MUST be totally relocatable.
 * Only the CODE chunck of your program will be loaded
 * The program must be terminated by a single RTS instruction



                  CALL (call a machine-code program)

CALL address[,params]
CALL bank[,params]

Executes an assembly language program held in the AMiga's memory.

  "addrss" can be either the absolute location of your code, or the
number of an AMOS memory bank which has been previously created with
PLOAD.

  On entry to your program, registers D0 to D7 and A0 to A2 will be
loaded from the values stored in the DREG and AREG arrays. Your
assembly language program can now change any 68000 register it likes.
At the start the routine, register A3 will point to the optional
parameter list, and A5 will contain the address of the main AMOS data
area. When your program's finished, you can return to Basic with just a
simple RTS instruction.

  "params" is a list of parameters which will be pushed onto the A3
stack by the CALL command. These parameters need to be removed in
REVERSE order. So the last value you entered into the instruction wlil
be the first on to the stack. Depending on the type of your parameters,
the values referenced by A3 will be in one of the following three
formats:

Integer : Holds a long word containing a normal AMOS integer.

F.Point : Contains a floating point number in IEEE single prec. format.

String  : Sotres the address of the string. All strings start with a
          single word containing their length.

WARNING! Never poke directly into a string! When a string is
initialised to a constant the string address will point to the original
assignment statement inside the current program listing! So if you
change this value, you'll affect your original source code. This is
obviously extremely unwise, and should be avoided. See EXAMPLE 21.1



               =AREG= (variable used to pass information                   286
                   to the 68000's address registers)

a=AREG(r)
AREG(r)=a

AREG is an array of six PSEUDO variables which are used to hold a copy
of the first six of the 68000's address registers. r can range from 0
to 6 and indicates the number of the address register which is to be
affected.

  Whenever the CALL command is executed, the contents of this array are
loaded automatically into address registers A0 to A2. At the end of the
function, they are then saved back with any new information which has
been placed in the appropriate registers.



               =DREG= (variable used to pass information
                    to the 68000's data registers)

d=DREG(r)
DREG(r)=d

This is an array of eight integers wihch holds a copy of the contents
of the 68000 data registers. r refers to the register number and can
range from 0 to 7 for D1 to D7 respectively.


Accessing the system libraries                                             287
==============================
AMOS also allows you to call up most of the Amiga's internal system
libraries directly from the ROM. These aren't particularly useful,
since all the really interesting calls have already been built into
AMOS!

  Don't use these routines unless you know precisely what you're doing.
The Amiga is notoriously difficult to program, and it's all to easy to
crash the system and generate the infamous GURU error by mistake.



                        =DOSCALL (DOS library)

r=DOSCALL(function)

Executes a function directly from the DOS library. "function" is the
offset to the appropriate function. See the Amiga ROM Kernel Manuals
for more details.

  Before using this function, you'll need to set some of the control
registers in D0 to D7 and A0 to A2 using the AREG and DREG functions.
WHen the routine exits back to Basic, the contents of D0 are returned
in r. Note: The return values will not be loaded into DREG and AREG.



                        =EXECALL (EXEC library)

r=EXECALL(function)

Performs a call to the Amiga's EXEC library. On entry, D0 to D7 and
A0 to A2 are loaded with the control settings from the DREG and AREG
arrays. r is returned holding the contents of D0.



                      =GFXCALL (Graphics library)

r=GFXCALL(function)

Calls a routine from the graphics library using the control values
stored in the DREG and AREG arrays.



                     =INTCALL (Intuition library)

r=INTCALL(function)

Executes a command from the Intuition library. As usual the control
values are loaded from DREG and AREG arrays, and r holds the result of
the call.

  Since AMOS doesn't use the standard intuition routine, this function
is especially dangerous. Only call it if you are already familiar with
the Amiga's intuition library.


Inside AMOS Basic                                                          288
=================
In order to provide full access to the inner workings of the AMOS
system for developers, we've included several "hooks" into the various
data areas. These are not intended for the casual programmer, but they
do enable adbanved users to create their own AMOS utilities.



                    =SCREEN BASE (get screen table)


table=SCREEN BASE

Returns the base address of the internal table used to hold the number
and position of your AMOS screens. See EXAMPLE 21.2



                    =SPRITE BASE (get sprite table)

table=SPRITE BASE(n)

Provides the address of the internal data list for sprite n. If this
sprite doesn't exist, then the address of the table will be zero.

  Negative values for n return the address of the optional MASK
associated with your sprite. "table" will now contain one of three
possible values, depending on the status of this mask:

table < 0   Indicates that there's no mask for this sprite at all
table = 0   Sprite n does have a mask, but it hasn't been generated
table > 0   This is the address of the Mask in memory. The first
            long word of this area holds the length of the mask, and
            the next is followed by the actual definition.

See EXAMPLE 21.3



                       =ICON BSE (get icon base)

table=ICON BASE(n)

Returns the address for icon n. The format of this information is
exactly the same as the previous SPRITE BASE function.









                           23: COMMAND INDEX                               289
                      ---------------------------

ABS ..................125       ACOS .................112
ADD .................. 39       AMAL .................186
AMAL FREEZE ..........193       AMAL ON/OFF ..........193
AMALERR ..............195       AMPLAY ...............193
AMREG ................193       ANIM .................205
ANIM FREEZE ..........206       ANIM ON/OFF ..........206
APPEAR ...............136       APPEND ...............269
AREG .................286       ASC .................. 58
AT ................... 91       ATAN .................113
AUTO VIEW ON/OFF .....121       AUTOBACK .............158
BANK TO MENU .........221       BAR .................. 68
BCHG .................284       BCLR .................285
BELL .................234       BGRAB ................ 31
BIN$ .................279       BLOAD ................ 51
BOB ..................155       BOB CLEAR ............161
BOB COL ..............170       BOB DRAW .............161
BOB OFF ..............163       BOB UPDATE ...........161
BOBSPRITE COL ........170       BOOM .................233
BORDER ...............101       BORDER$ .............. 98
BOX .................. 65       BREAK ON/OFF ......... 83
BSAVE ................ 51       BSET .................284
BTST .................284       CALL .................285
CDOWN ................ 93       CDOWN$ ............... 93
CENTRE ............... 96       CHANAN ...............195
CHANGE MOUSE .........165       CHANMV ...............195
CHANNEL ..............197       CHOICE ...........214,216
CHR$ ................. 58       CIRCLE ............... 66
CLEAR KEY ............251       CLEFT ................ 94
CLEFT$ ............... 94       CLINE ................ 96
CLIP ................. 71       CLOSE ................269
CLOSE EDITOR ......... 30       CLOSE WORKBENCH ...... 30
CLS ..................131       CLW ..................103
CMOVE ................ 90       COL ..................170
COLOUR ............... 62       COP LOGIC ............144
COP MOVE .............143       COP MOVEL ............143
COP RESET ............144       COP WAIT .............143
COPPER OFF ...........143       COPPER ON ............143
COPY .................281       COS ..................112
CRIGHT ............... 94       CRIGHT$ .............. 94
CUP .................. 93       CUP$ ................. 93
CURS ON/OFF .......... 95       CURS PEN ............. 96
DATA .................256       DEC .................. 39
DEEK .................280       DEF FN ...............118                  290
DEF SCROLL ...........133       DEFAULT ..............121
DEFAULT PALETTE ......131       DEGREE ...............111
DEL BLOCK ............210       DEL CBLOCK ...........211
DEL ICON .............209       DEL WAVE .............244
DFREE ................265       DIM .................. 36
DIR ..................262       DIR FIRST$ ...........267
DIR NEXT$ ............267       DIR$ .................263
DIRECT ............... 80       DO...LOOP ............ 79
DOKE .................280       DOSCALL ..............287
DOUBLE BUFFER ........156       DRAW ................. 65
DREG .................286       DUAL PLAYFIELD .......127
DUAL PRIORITY ........128       EDIT ................. 80
ELLIPSE .............. 66       END .................. 81
EOF ..................271       ERASE ................ 50
ERRN ................. 86       ERROR ................ 86
EVERY n GOSUB ........ 82       EVERY n PROC ......... 82
EVERY ON/OFF ......... 82       EXECALL ..............287
EXIST ................267       EXIT ................. 79
EXIT IF .............. 80       EXP ..................114
FADE .................137       FALSE ................259
FIELD ................272       FILL .................383
FIRE .................169       FIX ..................117
FLASH ................138       FLIP$ ................ 57
FN ...................118       FONT$ ................107
FOR...NEXT ........... 77       FREE ................. 53
FSEL$ ................266       GET ..................273
GET BLOCK ............209       GET BOB ..............163
GET CBLOCK ...........211       GET DISC FONTS .......107
GET FONTS ............106       GET ICON .............208
GET ICON PALETTE .....208       GET PALETTE ..........131
GET ROM FONTS ........107       GET SPRITE ...........107
GET SPRITE PALETTE ...151       GFXCALL ..............151
GLOBAL ............... 46       GOSUB ................ 46
GOTO ................. 74       GR LOCATE ............ 73
GR WRITING ........... 70       HCOS ................. 70
HEX$ .................279       HIDE .................279
HOME ................. 92       HOT SPOT ............. 92
SCROLL ............... 98       HSIN ................. 98
HSLIDER ..............104       HTAN .................104
HUNT .................282       HZONE ................173
I BOB ................162       I SPRITE .............154
ICON BASE ............154       IF..THEN..[ELSE] ..... 75
IF..[ELSE]..ENDIF .... 76       INC .................. 39
INK .................. 61       INKEY$ ...............249
INPUT ................252       INPUT # ..............269
INPUT$ ...............271       INPUT$() .............250
INSTR ................ 56       INT ..................115
INTCALL ..............287       INVERSE ON/OFF ....... 88                  291
JDOWN ................169       JLEFT ................168
JOY ..................168       JRIGHT ...............168
JUP ..................168       KEY SHIFT ............250
KEY SPEED ............251       KEY STATE ............250
KILL .................265       LDIR .................274
LED ..................248       LEEK .................280
LEFT$ ................ 58       LEN .................. 58
LENGTH ............... 50       LIMIT BOB ............162
LIMIT MOUSE ..........167       LINE INPUT ...........253
LINE INPUT # .........253       LIST BANK ............ 49
LLIST ................274       LN ...................114
LOAD ................. 51       LOAD IFF .............124
LOCATE ............... 90       LOF ..................271
LOG ..................114       LOGBASE ..............136
LOGIC ................136       LOKE .................281
LOWER$ ............... 57       LPRINT ...............274
MAKE ICON MASK .......209       MAKE MASK ............172
MATCH ................ 60       MAX ..................116
MEMORIZE X/Y ......... 95       MENU$ ............212,215
MENU ACTIVE ..........229       MENU BAR .............228
MENU BASE ............231       MENU CALC ............222
MENU CALLED ..........226       MENU DEL .............221
MENU INACTIVE ........229       MENU ITEM MOVABLE ....230
MENU ITEM STATIC .....230       MENU KEY .............219
MENU LINE ............227       MENU LINKED ..........231
MENU MOUSE ...........232       MENU MOVABLE .........229
MENU ON/OFF ..213,220,221       MENU ONCE ............227
MENU SEPARATE ........231       MENU STATIC ..........230
MENU TLINE ...........228       MENU TO BANK .........221
MENU X ...............231       MENU Y ...............231
MID$ ................. 54       MIN ..................117
MKDIR ................265       MOUSE CLICK ..........166
MOUSE KEY ............166       MOUSE ZONE ...........173
MOVE FREEZE ..........205       MOVE ON/OFF ..........205
MOVE X ...............203       MOVE Y ...............204
MOVON ................205       MUSIC ................238
MUSIC OFF ............238       MUSIC STOP ...........238
MVOLUME ..............239       NO MASK ..............158
NOISE ................244       NOT ..................258
ON ERROR GOTO ........ 83       ON ERROR PROC ........ 84
ON MENU DEL ..........218       ON MENU GOSUB ........218
ON MENU GOTO .........218       ON MENU ON/OFF .......218
ON MENU PROC ......... 81       ON...GOSUB ........... 81
ON...GOTO ............ 81       ON...PROC ............ 81
OPEN IN ..............269       OPEN OUT .............269
OPEN PORT ............274       OPEN RANDOM ..........272
PACK .................277       PAINT ................ 67
PALETTE .............. 63       PAPER ................ 87
PAPER$ ............... 88       PARAM ................ 46
PARENT ...............264       PASTE BOB ............163
PASTE ICON ...........207       PEEK .................279
PEN .................. 87       PEN$ ................. 87
PHYBASE ..............135       PHYSIC ...............135
PI# ..................240       PLAY .................240
PLOAD ................285       PLOT ................. 64
POF ..................271       POINT ................ 64
POKE .................280       POLYGON .............. 68
POLYLINE ............. 65       POP .................. 75
POP PROC ............. 47       PORT .................275
PRG FIRST$ ........... 31       PRG NEXT$ ............ 31
PRINT # ..............269       PRINT / ? ............254
PRIORITY ON/OFF ......174       PROCEDURE ............ 42
PRUN ................. 31       PSEL$ ................ 32
PUT ..................273       PUT BLOCK ............210
PUT BOB ..............163       PUT CBLOCK ...........211
PUT KEY ..............252       RADIAN ...............111
RAIN .................141       RAINBOW ..............141
RANDOMIZE ............116       READ .................256
REM / ' ..............255       REMEMBER X/Y ......... 96
RENAME ...............265       REPEAT$ .............. 97
REPEAT...UNTIL ....... 78       RESERVE .............. 49
RESERVE ZONE .........172       RESET ZONE ...........174
RESTORE ..............257       RESUME ............... 85                  292
RETURN ............... 74       RIGHT$ ............... 54
RND ..................115       ROL ..................282
ROR ..................283       RUN ..................266
SAM BANK .............236       SAM LOOP .............237
SAM PLAY .............235       SAM RAW ..............236
SAMPLE ...............244       SAVE ................. 51
SAVE IFF .............124       SAY ..................247
SCAN$ ................ 29       SCANCODE .............249
SCIN .................130       SCREEN ...............129
SCREEN BASE ..........288       SCREEN CLONE .........127
SCREEN CLOSE .........121       SCREEN COLOUR ........130
SCREEN COPY ..........132       SCREEN DISPLAY .......125
SCREEN HEIGHT ........130       SCREEN HIDE ..........129
SCREEN OFFSET ........126       SCREEN OPEN ..........119
SCREEN SHOW ..........130       SCREEN SWAP ..........134
SCREEN TO BACK .......129       SCREEN TO FRONT ......129
SCREEN WIDTH .........130       SCROLL ...............134
SET BOB ..............157       SET BUFFER ........... 53
SET CURS ............. 95       SET DIR ..............264
SET ENVEL ............245       SET FONT .............108
SET INPUT ............270       STE LINE ............. 67
SET MENU .............232       SET PAINT ............ 70
SET PATTERN .......... 69       SET RAINBOW ..........139
SET SLIDER ...........104       SET SPRITE BUFFER ....151                  293
SET TAB .............. 97       SET TALK .............247
SET TEMPRAS .......... 71       SET TEXT .............108
SET WAVE .............241       SET ZONE .............172
SGN ..................115       SHADE ON/OFF ......... 88
SHARED ............... 45       SHIFT DOWN ...........139
SHIFT OFF ............139       SHIFT UP .............138
SHOOT ................233       SHOW .................165
SIN ..................111       SORT ................. 59
SPACE$ ............... 57       SPACK ................276
SPRITE ...............145       SPRITE BASE ..........288
SPRITE COL ...........169       SPRITE OFF ...........152
SPRITEBOB COL ........170       SPRITE UPDATE ........152
SQR ..................114       START ................ 50
STR$ ................. 59       STRING$ .............. 58
SWAP .................117       SYNCHRO ..............202
TAB$ ................. 97       TAN ..................112
TEMPO ................239       TEXT .................106
TEXT BASE ............109       TEXT LENGTH ..........109
TEXT STYLE ...........109       TIMER ................258
TITLE BOTTOM .........101       TITLE TOP ............101
TRUE .................258       UNDER ON/OFF ......... 89
UNPACK ...............277       UPDATE ...............175
UPDATE EVERY .........201       UPPER$ ............... 57
USING ................254       VAL .................. 59
VARPTR ...............281       VIEW .................121
VOICE ................239       VOLUME ...............235
VSCROLL .............. 99       VSLIDER ..............104
VUMETER ..............240       WAIT .................258
WAIT KEY .............259       WAIT VBL .............136
WAVE .................243       WHILE...WEND ......... 78
WIND CLOSE ...........102       WIND MOVE ............102
WIND SIZE ............103       WINDON ...............102
WINDOPEN ............. 99       WINDOW ...............102
WINDOW FONT ..........100       WINDSAVE .............100
WRITING .............. 89       X BOB ................162
X GRAPHIC ............ 92       X HARD ...............154
X MOUSE ..............167       X SCREEN .............153
X SPRITE .............152       XCURS ................ 94
XGR .................. 64       XTEXT ................ 91
Y BOB ................162       Y GRAPHIC ............ 92
Y HARD ...............154       Y MOUSE ..............167
Y SCREEN .............153       Y SPRITE .............153